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
  32 /** @defgroup XBT_mallocator_cons Mallocator constructor and destructor
  33  *  @ingroup XBT_mallocator
  34  *
  35  *  @{
  36  */
  37
  38 /** \brief Mallocator data type (opaque structure) */
  39 typedef struct s_xbt_mallocator *xbt_mallocator_t;
  40 XBT_PUBLIC xbt_mallocator_t xbt_mallocator_new(int size, pvoid_f_void_t new_f, void_f_pvoid_t free_f, void_f_pvoid_t reset_f);
  41 XBT_PUBLIC void xbt_mallocator_free(xbt_mallocator_t mallocator);
  42 /** @} */
  43
  44 /* object handling */
  45 /** @defgroup XBT_mallocator_objects Mallocator object handling
  46  *  @ingroup XBT_mallocator
  47  *
  48  *  @{
  49  */
  50 XBT_PUBLIC void *xbt_mallocator_get(xbt_mallocator_t mallocator);
  51 XBT_PUBLIC void xbt_mallocator_release(xbt_mallocator_t mallocator, void *object);
  52 /** @} */
  53
  54 SG_END_DECL()
  55
  56 #endif /* _XBT_MALLOCATOR_H */