From 421598739fa7167a9c4fac25b1038630f8b7fcf3 Mon Sep 17 00:00:00 2001 From: thiery Date: Fri, 4 Aug 2006 08:07:14 +0000 Subject: [PATCH 1/1] Add Doxygen documentation for mallocators git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2688 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- doc/module-xbt.doc | 2 ++ include/xbt/mallocator.h | 40 +++++++++++++++++++++++-- src/xbt/mallocator.c | 64 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 100 insertions(+), 6 deletions(-) diff --git a/doc/module-xbt.doc b/doc/module-xbt.doc index cdcdd06753..61ffc473e4 100644 --- a/doc/module-xbt.doc +++ b/doc/module-xbt.doc @@ -8,6 +8,7 @@ - \ref XBT_log - \ref XBT_error - \ref XBT_config + - \ref XBT_mallocator - Data structures - \ref XBT_dynar - \ref XBT_dict @@ -40,6 +41,7 @@ /** @defgroup XBT_log Logging support */ /** @defgroup XBT_error Assert macro familly */ /** @defgroup XBT_config Configuration support */ + /** @defgroup XBT_mallocator Mallocators */ /** @} */ diff --git a/include/xbt/mallocator.h b/include/xbt/mallocator.h index ff13879736..50ae0ff11b 100644 --- a/include/xbt/mallocator.h +++ b/include/xbt/mallocator.h @@ -1,3 +1,10 @@ +/* xbt/mallocator.h -- api to recycle allocated objects */ + +/* Copyright (c) 2006 Christophe Thiery. All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #ifndef _XBT_MALLOCATOR_H #define _XBT_MALLOCATOR_H @@ -6,16 +13,43 @@ SG_BEGIN_DECL() -/* mallocator data type (opaque structure) */ -typedef struct s_xbt_mallocator *xbt_mallocator_t; +/** @addtogroup XBT_mallocator + * @brief The mallocator system + * + * This section describes the API to a mallocator. + * A mallocator allows you to recycle the objects you don't need anymore + * instead of freeing them. A mallocator is a stack which stores the unused objects + * or a given type. If you often need to malloc() / free() objects of a certain + * type, you should use a mallocator and call \a xbt_mallocator_get() and + * \a xbt_mallocator_release() instead of malloc() and free(). + * + * When you release an object, it is not freed but it is stored + * into the mallocator (unless the mallocator is full). And when you want to get a + * new object, the object is just extracted from the mallocator. No malloc() is + * done, unless there is no more object in the mallocator. + */ + +/** @defgroup XBT_mallocator_cons Mallocator constructor and destructor + * @ingroup XBT_mallocator + * + * @{ + */ -/* creation and destruction */ +/** \brief Mallocator data type (opaque structure) */ +typedef struct s_xbt_mallocator *xbt_mallocator_t; 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); void xbt_mallocator_free(xbt_mallocator_t mallocator); +/** @} */ /* object handling */ +/** @defgroup XBT_mallocator_objects Mallocator object handling + * @ingroup XBT_mallocator + * + * @{ + */ void *xbt_mallocator_get(xbt_mallocator_t mallocator); void xbt_mallocator_release(xbt_mallocator_t mallocator, void *object); +/** @} */ SG_END_DECL() diff --git a/src/xbt/mallocator.c b/src/xbt/mallocator.c index c2b1d3c003..ff9557f0c2 100644 --- a/src/xbt/mallocator.c +++ b/src/xbt/mallocator.c @@ -1,8 +1,32 @@ +/* dict - a generic dictionnary, variation over the B-tree concept */ + +/* Copyright (c) 2006 Christophe Thiery. All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + #include "xbt/mallocator.h" #include "xbt/asserts.h" #include "xbt/sysdep.h" #include "mallocator_private.h" +/** + * \brief Constructor + * \param size size of the internal stack: number of objects the mallocator + * will be able to store + * \param new_f function to allocate a new object of your datatype, called + * in \a xbt_mallocator_get() when the mallocator is empty + * \param free_f function to free an object of your datatype, called + * in \a xbt_mallocator_release() when the stack is full, and when + * the mallocator is freed. + * \param reset_f function to reinitialise an object of your datatype, called + * when you extract an object from the mallocator + * + * Create and initialize a new mallocator for a given datatype. + * + * \return pointer to the created mallocator + * \see xbt_mallocator_free() + */ xbt_mallocator_t xbt_mallocator_new(int size, pvoid_f_void_t new_f, void_f_pvoid_t free_f, @@ -22,7 +46,14 @@ xbt_mallocator_t xbt_mallocator_new(int size, return m; } -/* Destroy the mallocator and all its data */ +/** \brief Destructor + * \param m the mallocator you want to destroy + * + * Destroy the mallocator and all its data. The function + * free_f is called on each object in the mallocator. + * + * \see xbt_mallocator_new() + */ void xbt_mallocator_free(xbt_mallocator_t m) { xbt_assert0(m != NULL, "Invalid parameter"); @@ -34,7 +65,22 @@ void xbt_mallocator_free(xbt_mallocator_t m) { xbt_free(m); } -/* Return an object (use this function instead of malloc) */ +/** + * \brief Extract an object from a mallocator + * \param m a mallocator + * + * Remove an object from the mallocator and return it. + * This function is designed to be used instead of malloc(). + * If the mallocator is not empty, an object is + * extracted from the mallocator and no malloc is done. + * + * If the mallocator is empty, a new object is created, + * by calling the function new_f(). + * + * In both cases, the function reset_f() is called on the object. + * + * \see xbt_mallocator_release() + */ void *xbt_mallocator_get(xbt_mallocator_t m) { xbt_assert0(m != NULL, "Invalid parameter"); @@ -51,7 +97,19 @@ void *xbt_mallocator_get(xbt_mallocator_t m) { return object; } -/* Release an object (use this function instead of free) */ +/** \brief Push an object into a mallocator + * \param m a mallocator + * \param object an object you don't need anymore + * + * Push into the mallocator an object you don't need anymore. + * This function is designed to be used instead of free(). + * If the mallocator is not full, your object if stored into + * the mallocator and no free is done. + * If the mallocator is full, the object is freed by calling + * the function free_f(). + * + * \see xbt_mallocator_get() + */ void xbt_mallocator_release(xbt_mallocator_t m, void *object) { xbt_assert0(m != NULL && object != NULL, "Invalid parameter"); -- 2.20.1