include/xbt/mallocator.h

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