home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / mem.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  14.9 KB  |  544 lines
  1. /*
  2.  * Copyright (C) 2004-2006  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1997-2001  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: mem.h,v 1.59.18.9 2006/01/04 23:50:23 marka Exp $ */
  19.  
  20. #ifndef ISC_MEM_H
  21. #define ISC_MEM_H 1
  22.  
  23. /*! \file */
  24.  
  25. #include <stdio.h>
  26.  
  27. #include <isc/lang.h>
  28. #include <isc/mutex.h>
  29. #include <isc/platform.h>
  30. #include <isc/types.h>
  31.  
  32. ISC_LANG_BEGINDECLS
  33.  
  34. #define ISC_MEM_LOWATER 0
  35. #define ISC_MEM_HIWATER 1
  36. typedef void (*isc_mem_water_t)(void *, int);
  37.  
  38. typedef void * (*isc_memalloc_t)(void *, size_t);
  39. typedef void (*isc_memfree_t)(void *, void *);
  40.  
  41. /*%
  42.  * Define ISC_MEM_DEBUG=1 to make all functions that free memory
  43.  * set the pointer being freed to NULL after being freed.
  44.  * This is the default; set ISC_MEM_DEBUG=0 to disable it.
  45.  */
  46. #ifndef ISC_MEM_DEBUG
  47. #define ISC_MEM_DEBUG 1
  48. #endif
  49.  
  50. /*%
  51.  * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
  52.  * allocation and freeing by file and line number.
  53.  */
  54. #ifndef ISC_MEM_TRACKLINES
  55. #define ISC_MEM_TRACKLINES 1
  56. #endif
  57.  
  58. /*%
  59.  * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
  60.  * the requested space.  This will increase the size of each allocation.
  61.  */
  62. #ifndef ISC_MEM_CHECKOVERRUN
  63. #define ISC_MEM_CHECKOVERRUN 1
  64. #endif
  65.  
  66. /*%
  67.  * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
  68.  * with the byte string '0xbe'.  This helps track down uninitialized pointers
  69.  * and the like.  On freeing memory, the space is filled with '0xde' for
  70.  * the same reasons.
  71.  */
  72. #ifndef ISC_MEM_FILL
  73. #define ISC_MEM_FILL 1
  74. #endif
  75.  
  76. /*%
  77.  * Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic
  78.  * name so that the leaking pool can be more readily identified in
  79.  * case of a memory leak.
  80.  */
  81. #ifndef ISC_MEMPOOL_NAMES
  82. #define ISC_MEMPOOL_NAMES 1
  83. #endif
  84.  
  85. LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
  86. /*@{*/
  87. #define ISC_MEM_DEBUGTRACE        0x00000001U
  88. #define ISC_MEM_DEBUGRECORD        0x00000002U
  89. #define ISC_MEM_DEBUGUSAGE        0x00000004U
  90. #define ISC_MEM_DEBUGSIZE        0x00000008U
  91. #define ISC_MEM_DEBUGCTX        0x00000010U
  92. #define ISC_MEM_DEBUGALL        0x0000001FU
  93. /*!<
  94.  * The variable isc_mem_debugging holds a set of flags for
  95.  * turning certain memory debugging options on or off at
  96.  * runtime.  Its is intialized to the value ISC_MEM_DEGBUGGING,
  97.  * which is 0 by default but may be overridden at compile time.
  98.  * The following flags can be specified:
  99.  *
  100.  * \li #ISC_MEM_DEBUGTRACE
  101.  *    Log each allocation and free to isc_lctx.
  102.  *
  103.  * \li #ISC_MEM_DEBUGRECORD
  104.  *    Remember each allocation, and match them up on free.
  105.  *    Crash if a free doesn't match an allocation.
  106.  *
  107.  * \li #ISC_MEM_DEBUGUSAGE
  108.  *    If a hi_water mark is set, print the maximium inuse memory
  109.  *    every time it is raised once it exceeds the hi_water mark.
  110.  *
  111.  * \li #ISC_MEM_DEBUGSIZE
  112.  *    Check the size argument being passed to isc_mem_put() matches
  113.  *    that passed to isc_mem_get().
  114.  *
  115.  * \li #ISC_MEM_DEBUGCTX
  116.  *    Check the mctx argument being passed to isc_mem_put() matches
  117.  *    that passed to isc_mem_get().
  118.  */
  119. /*@}*/
  120.  
  121. #if ISC_MEM_TRACKLINES
  122. #define _ISC_MEM_FILELINE    , __FILE__, __LINE__
  123. #define _ISC_MEM_FLARG        , const char *, int
  124. #else
  125. #define _ISC_MEM_FILELINE
  126. #define _ISC_MEM_FLARG
  127. #endif
  128.  
  129. /*!
  130.  * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
  131.  * implementation in preference to the system one.  The internal malloc()
  132.  * is very space-efficient, and quite fast on uniprocessor systems.  It
  133.  * performs poorly on multiprocessor machines.
  134.  * JT: we can overcome the performance issue on multiprocessor machines
  135.  * by carefully separating memory contexts.
  136.  */
  137.  
  138. #ifndef ISC_MEM_USE_INTERNAL_MALLOC
  139. #define ISC_MEM_USE_INTERNAL_MALLOC 1
  140. #endif
  141.  
  142. /*
  143.  * Flags for isc_mem_create2()calls.
  144.  */
  145. #define ISC_MEMFLAG_NOLOCK    0x00000001     /* no lock is necessary */
  146. #define ISC_MEMFLAG_INTERNAL    0x00000002     /* use internal malloc */
  147. #if ISC_MEM_USE_INTERNAL_MALLOC
  148. #define ISC_MEMFLAG_DEFAULT     ISC_MEMFLAG_INTERNAL
  149. #else
  150. #define ISC_MEMFLAG_DEFAULT     0
  151. #endif
  152.  
  153.  
  154. #define isc_mem_get(c, s)    isc__mem_get((c), (s) _ISC_MEM_FILELINE)
  155. #define isc_mem_allocate(c, s)    isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
  156. #define isc_mem_strdup(c, p)    isc__mem_strdup((c), (p) _ISC_MEM_FILELINE)
  157. #define isc_mempool_get(c)    isc__mempool_get((c) _ISC_MEM_FILELINE)
  158.  
  159. /*% 
  160.  * isc_mem_putanddetach() is a convienence function for use where you
  161.  * have a structure with an attached memory context.
  162.  *
  163.  * Given:
  164.  *
  165.  * \code
  166.  * struct {
  167.  *    ...
  168.  *    isc_mem_t *mctx;
  169.  *    ...
  170.  * } *ptr;
  171.  *
  172.  * isc_mem_t *mctx;
  173.  *
  174.  * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
  175.  * \endcode
  176.  *
  177.  * is the equivalent of:
  178.  *
  179.  * \code
  180.  * mctx = NULL;
  181.  * isc_mem_attach(ptr->mctx, &mctx);
  182.  * isc_mem_detach(&ptr->mctx);
  183.  * isc_mem_put(mctx, ptr, sizeof(*ptr));
  184.  * isc_mem_detach(&mctx);
  185.  * \endcode
  186.  */
  187.  
  188. #if ISC_MEM_DEBUG
  189. #define isc_mem_put(c, p, s) \
  190.     do { \
  191.         isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
  192.         (p) = NULL; \
  193.     } while (0)
  194. #define isc_mem_putanddetach(c, p, s) \
  195.     do { \
  196.         isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
  197.         (p) = NULL; \
  198.     } while (0)
  199. #define isc_mem_free(c, p) \
  200.     do { \
  201.         isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
  202.         (p) = NULL; \
  203.     } while (0)
  204. #define isc_mempool_put(c, p) \
  205.     do { \
  206.         isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
  207.         (p) = NULL; \
  208.     } while (0)
  209. #else
  210. #define isc_mem_put(c, p, s)    isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE)
  211. #define isc_mem_putanddetach(c, p, s) \
  212.     isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE)
  213. #define isc_mem_free(c, p)    isc__mem_free((c), (p) _ISC_MEM_FILELINE)
  214. #define isc_mempool_put(c, p)    isc__mempool_put((c), (p) _ISC_MEM_FILELINE)
  215. #endif
  216.  
  217. /*@{*/
  218. isc_result_t 
  219. isc_mem_create(size_t max_size, size_t target_size,
  220.            isc_mem_t **mctxp);
  221.  
  222. isc_result_t
  223. isc_mem_create2(size_t max_size, size_t target_size,
  224.         isc_mem_t **mctxp, unsigned int flags);
  225.  
  226. isc_result_t 
  227. isc_mem_createx(size_t max_size, size_t target_size,
  228.         isc_memalloc_t memalloc, isc_memfree_t memfree,
  229.         void *arg, isc_mem_t **mctxp);
  230.  
  231. isc_result_t 
  232. isc_mem_createx2(size_t max_size, size_t target_size,
  233.          isc_memalloc_t memalloc, isc_memfree_t memfree,
  234.          void *arg, isc_mem_t **mctxp, unsigned int flags);
  235.  
  236. /*!<
  237.  * \brief Create a memory context.
  238.  *
  239.  * 'max_size' and 'target_size' are tuning parameters.  When
  240.  * ISC_MEMFLAG_INTERNAL is set, allocations smaller than 'max_size'
  241.  * will be satisfied by getting blocks of size 'target_size' from the
  242.  * system allocator and breaking them up into pieces; larger allocations
  243.  * will use the system allocator directly. If 'max_size' and/or
  244.  * 'target_size' are zero, default values will be * used.  When
  245.  * ISC_MEMFLAG_INTERNAL is not set, 'target_size' is ignored.
  246.  *
  247.  * 'max_size' is also used to size the statistics arrays and the array
  248.  * used to record active memory when ISC_MEM_DEBUGRECORD is set.  Settin
  249.  * 'max_size' too low can have detrimental effects on performance.
  250.  *
  251.  * A memory context created using isc_mem_createx() will obtain
  252.  * memory from the system by calling 'memalloc' and 'memfree',
  253.  * passing them the argument 'arg'.  A memory context created
  254.  * using isc_mem_create() will use the standard library malloc()
  255.  * and free().
  256.  *
  257.  * If ISC_MEMFLAG_NOLOCK is set in 'flags', the corresponding memory context
  258.  * will be accessed without locking.  The user who creates the context must
  259.  * ensure there be no race.  Since this can be a source of bug, it is generally
  260.  * inadvisable to use this flag unless the user is very sure about the race
  261.  * condition and the access to the object is highly performance sensitive.
  262.  *
  263.  * Requires:
  264.  * mctxp != NULL && *mctxp == NULL */
  265. /*@}*/
  266.  
  267. /*@{*/
  268. void 
  269. isc_mem_attach(isc_mem_t *, isc_mem_t **);
  270. void 
  271. isc_mem_detach(isc_mem_t **);
  272. /*!<
  273.  * \brief Attach to / detach from a memory context.
  274.  *
  275.  * This is intended for applications that use multiple memory contexts
  276.  * in such a way that it is not obvious when the last allocations from
  277.  * a given context has been freed and destroying the context is safe.
  278.  * 
  279.  * Most applications do not need to call these functions as they can
  280.  * simply create a single memory context at the beginning of main()
  281.  * and destroy it at the end of main(), thereby guaranteeing that it
  282.  * is not destroyed while there are outstanding allocations.
  283.  */
  284. /*@}*/
  285.  
  286. void 
  287. isc_mem_destroy(isc_mem_t **);
  288. /*%<
  289.  * Destroy a memory context.
  290.  */
  291.  
  292. isc_result_t 
  293. isc_mem_ondestroy(isc_mem_t *ctx,
  294.           isc_task_t *task,
  295.           isc_event_t **event);
  296. /*%<
  297.  * Request to be notified with an event when a memory context has
  298.  * been successfully destroyed.
  299.  */
  300.  
  301. void 
  302. isc_mem_stats(isc_mem_t *mctx, FILE *out);
  303. /*%<
  304.  * Print memory usage statistics for 'mctx' on the stream 'out'.
  305.  */
  306.  
  307. void 
  308. isc_mem_setdestroycheck(isc_mem_t *mctx,
  309.             isc_boolean_t on);
  310. /*%<
  311.  * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
  312.  * destroyed and abort the program if any are present.
  313.  */
  314.  
  315. /*@{*/
  316. void 
  317. isc_mem_setquota(isc_mem_t *, size_t);
  318. size_t 
  319. isc_mem_getquota(isc_mem_t *);
  320. /*%<
  321.  * Set/get the memory quota of 'mctx'.  This is a hard limit
  322.  * on the amount of memory that may be allocated from mctx;
  323.  * if it is exceeded, allocations will fail.
  324.  */
  325. /*@}*/
  326.  
  327. size_t 
  328. isc_mem_inuse(isc_mem_t *mctx);
  329. /*%<
  330.  * Get an estimate of the number of memory in use in 'mctx', in bytes.
  331.  * This includes quantization overhead, but does not include memory
  332.  * allocated from the system but not yet used.
  333.  */
  334.  
  335. void
  336. isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
  337.          size_t hiwater, size_t lowater);
  338. /*%<
  339.  * Set high and low water marks for this memory context.  
  340.  * 
  341.  * When the memory
  342.  * usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, #ISC_MEM_HIWATER)'
  343.  * will be called.  When the usage drops below 'lowater', 'water' will
  344.  * again be called, this time with #ISC_MEM_LOWATER.
  345.  *
  346.  * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
  347.  * ignored and the state is reset.
  348.  *
  349.  * Requires:
  350.  *
  351.  *    'water' is not NULL.
  352.  *    hi_water >= lo_water
  353.  */
  354.  
  355. void
  356. isc_mem_printactive(isc_mem_t *mctx, FILE *file);
  357. /*%<
  358.  * Print to 'file' all active memory in 'mctx'.
  359.  *
  360.  * Requires ISC_MEM_DEBUGRECORD to have been set.
  361.  */
  362.  
  363. void
  364. isc_mem_printallactive(FILE *file);
  365. /*%<
  366.  * Print to 'file' all active memory in all contexts.
  367.  *
  368.  * Requires ISC_MEM_DEBUGRECORD to have been set.
  369.  */
  370.  
  371. void
  372. isc_mem_checkdestroyed(FILE *file);
  373. /*%<
  374.  * Check that all memory contexts have been destroyed.
  375.  * Prints out those that have not been.
  376.  * Fatally fails if there are still active contexts.
  377.  */
  378.  
  379. /*
  380.  * Memory pools
  381.  */
  382.  
  383. isc_result_t
  384. isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
  385. /*%<
  386.  * Create a memory pool.
  387.  *
  388.  * Requires:
  389.  *\li    mctx is a valid memory context.
  390.  *\li    size > 0
  391.  *\li    mpctxp != NULL and *mpctxp == NULL
  392.  *
  393.  * Defaults:
  394.  *\li    maxalloc = UINT_MAX
  395.  *\li    freemax = 1
  396.  *\li    fillcount = 1
  397.  *
  398.  * Returns:
  399.  *\li    #ISC_R_NOMEMORY        -- not enough memory to create pool
  400.  *\li    #ISC_R_SUCCESS        -- all is well.
  401.  */
  402.  
  403. void
  404. isc_mempool_destroy(isc_mempool_t **mpctxp);
  405. /*%<
  406.  * Destroy a memory pool.
  407.  *
  408.  * Requires:
  409.  *\li    mpctxp != NULL && *mpctxp is a valid pool.
  410.  *\li    The pool has no un"put" allocations outstanding
  411.  */
  412.  
  413. void
  414. isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
  415. /*%<
  416.  * Associate a name with a memory pool.  At most 15 characters may be used.
  417.  *
  418.  * Requires:
  419.  *\li    mpctx is a valid pool.
  420.  *\li    name != NULL;
  421.  */
  422.  
  423. void
  424. isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
  425. /*%<
  426.  * Associate a lock with this memory pool.
  427.  *
  428.  * This lock is used when getting or putting items using this memory pool,
  429.  * and it is also used to set or get internal state via the isc_mempool_get*()
  430.  * and isc_mempool_set*() set of functions.
  431.  *
  432.  * Mutiple pools can each share a single lock.  For instance, if "manager"
  433.  * type object contained pools for various sizes of events, and each of
  434.  * these pools used a common lock.  Note that this lock must NEVER be used
  435.  * by other than mempool routines once it is given to a pool, since that can
  436.  * easily cause double locking.
  437.  *
  438.  * Requires:
  439.  *
  440.  *\li    mpctpx is a valid pool.
  441.  *
  442.  *\li    lock != NULL.
  443.  *
  444.  *\li    No previous lock is assigned to this pool.
  445.  *
  446.  *\li    The lock is initialized before calling this function via the normal
  447.  *    means of doing that.
  448.  */
  449.  
  450. /*
  451.  * The following functions get/set various parameters.  Note that due to
  452.  * the unlocked nature of pools these are potentially random values unless
  453.  * the imposed externally provided locking protocols are followed.
  454.  *
  455.  * Also note that the quota limits will not always take immediate effect.
  456.  * For instance, setting "maxalloc" to a number smaller than the currently
  457.  * allocated count is permitted.  New allocations will be refused until
  458.  * the count drops below this threshold.
  459.  *
  460.  * All functions require (in addition to other requirements):
  461.  *    mpctx is a valid memory pool
  462.  */
  463.  
  464. unsigned int
  465. isc_mempool_getfreemax(isc_mempool_t *mpctx);
  466. /*%<
  467.  * Returns the maximum allowed size of the free list.
  468.  */
  469.  
  470. void
  471. isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
  472. /*%<
  473.  * Sets the maximum allowed size of the free list.
  474.  */
  475.  
  476. unsigned int
  477. isc_mempool_getfreecount(isc_mempool_t *mpctx);
  478. /*%<
  479.  * Returns current size of the free list.
  480.  */
  481.  
  482. unsigned int
  483. isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
  484. /*!<
  485.  * Returns the maximum allowed number of allocations.
  486.  */
  487.  
  488. void
  489. isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
  490. /*%<
  491.  * Sets the maximum allowed number of allocations.
  492.  *
  493.  * Additional requirements:
  494.  *\li    limit > 0
  495.  */
  496.  
  497. unsigned int
  498. isc_mempool_getallocated(isc_mempool_t *mpctx);
  499. /*%<
  500.  * Returns the number of items allocated from this pool.
  501.  */
  502.  
  503. unsigned int
  504. isc_mempool_getfillcount(isc_mempool_t *mpctx);
  505. /*%<
  506.  * Returns the number of items allocated as a block from the parent memory
  507.  * context when the free list is empty.
  508.  */
  509.  
  510. void
  511. isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
  512. /*%<
  513.  * Sets the fillcount.
  514.  *
  515.  * Additional requirements:
  516.  *\li    limit > 0
  517.  */
  518.  
  519.  
  520. /*
  521.  * Pseudo-private functions for use via macros.  Do not call directly.
  522.  */
  523. void *        
  524. isc__mem_get(isc_mem_t *, size_t _ISC_MEM_FLARG);
  525. void         
  526. isc__mem_putanddetach(isc_mem_t **, void *,
  527.                       size_t _ISC_MEM_FLARG);
  528. void         
  529. isc__mem_put(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
  530. void *        
  531. isc__mem_allocate(isc_mem_t *, size_t _ISC_MEM_FLARG);
  532. void        
  533. isc__mem_free(isc_mem_t *, void * _ISC_MEM_FLARG);
  534. char *        
  535. isc__mem_strdup(isc_mem_t *, const char *_ISC_MEM_FLARG);
  536. void *        
  537. isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
  538. void         
  539. isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
  540.  
  541. ISC_LANG_ENDDECLS
  542.  
  543. #endif /* ISC_MEM_H */
  544.