include/xbt/mallocator.h

   1 /* xbt/mallocator.h -- api to recycle allocated objects                     */
   2
   3 /* Copyright (c) 2006 Christophe Thiery. All rights reserved.               */
   4
   5 /* This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the license (GNU LGPL) which comes with this package. */
   7
   8 #ifndef _XBT_MALLOCATOR_H
   9 #define _XBT_MALLOCATOR_H
  10
  11 #include "xbt/function_types.h"
  12 #include "xbt/misc.h"           /* SG_BEGIN_DECL */
  13
  14 SG_BEGIN_DECL()
  15
  16 /** @addtogroup XBT_mallocator
  17  *  @brief The mallocator system
  18  *
  19  *  This section describes the API to a mallocator.
  20  *  A mallocator allows you to recycle the objects you don't need anymore
  21  *  instead of freeing them. A mallocator is a stack which stores the unused objects
  22  *  or a given type. If you often need to malloc() / free() objects of a certain
  23  *  type, you should use a mallocator and call \a xbt_mallocator_get() and
  24  *  \a xbt_mallocator_release() instead of malloc() and free().
  25  *
  26  *  When you release an object, it is not freed but it is stored
  27  *  into the mallocator (unless the mallocator is full). And when you want to get a
  28  *  new object, the object is just extracted from the mallocator. No malloc() is
  29  *  done, unless there is no more object in the mallocator.
  30  */
  31 /** @defgroup XBT_mallocator_cons Mallocator constructor and destructor
  32  *  @ingroup XBT_mallocator
  33  *
  34  *  @{
  35  */
  36 /** \brief Mallocator data type (opaque structure) */
  37      typedef struct s_xbt_mallocator *xbt_mallocator_t;
  38 XBT_PUBLIC(xbt_mallocator_t) xbt_mallocator_new(int size,
  39                                                 pvoid_f_void_t new_f,
  40                                                 void_f_pvoid_t free_f,
  41                                                 void_f_pvoid_t reset_f);
  42 XBT_PUBLIC(void) xbt_mallocator_free(xbt_mallocator_t mallocator);
  43 /** @} */
  44
  45 /* object handling */
  46 /** @defgroup XBT_mallocator_objects Mallocator object handling
  47  *  @ingroup XBT_mallocator
  48  *
  49  *  @{
  50  */
  51 XBT_PUBLIC(void *) xbt_mallocator_get(xbt_mallocator_t mallocator);
  52 XBT_PUBLIC(void) xbt_mallocator_release(xbt_mallocator_t mallocator,
  53                                         void *object);
  54 /** @} */
  55
  56 SG_END_DECL()
  57 #endif /* _XBT_MALLOCATOR_H */