[SCM] Samba Shared Repository - branch master updated -
release-4-0-0alpha7-638-gdb447d0
Volker Lendecke
vlendec at samba.org
Sat Mar 21 18:02:38 GMT 2009
The branch, master has been updated
via db447d0c476699dbf7fa0567c67f5938674ec811 (commit)
via cfce2d3611f225244fadf3d27d76371827fd6422 (commit)
via ba42320c7e9f5ccbd32eccbfb1f2d77e13b3a318 (commit)
via 3f9c30022a53a37ad829f8882a9a5161fcadda8b (commit)
via d21212c9192b41a3fdc7e96cb9bf0125a1dc6c2d (commit)
via f55e84e904173bed8dc9099ad523ca1e7be12355 (commit)
from 3b73cdb41201dd545e019e8e8313f6b8c51c7226 (commit)
http://gitweb.samba.org/?p=samba.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit db447d0c476699dbf7fa0567c67f5938674ec811
Author: Volker Lendecke <vl at samba.org>
Date: Sat Mar 21 16:58:54 2009 +0100
Reformatting
commit cfce2d3611f225244fadf3d27d76371827fd6422
Author: Volker Lendecke <vl at samba.org>
Date: Sat Mar 21 16:52:13 2009 +0100
Add some initial hook to the front page
commit ba42320c7e9f5ccbd32eccbfb1f2d77e13b3a318
Author: Volker Lendecke <vl at samba.org>
Date: Sat Mar 21 16:50:58 2009 +0100
Add a default "undocumented" module
commit 3f9c30022a53a37ad829f8882a9a5161fcadda8b
Author: Volker Lendecke <vl at samba.org>
Date: Sat Mar 21 16:40:33 2009 +0100
Delete talloc_guide.txt
commit d21212c9192b41a3fdc7e96cb9bf0125a1dc6c2d
Author: Volker Lendecke <vl at samba.org>
Date: Sat Mar 21 12:43:08 2009 +0100
Convert the contents of talloc_guide.txt to doxygen-style talloc.h comments
talloc_guide.txt was partly outdated, and as going through talloc.h now shows
it was incomplete.
commit f55e84e904173bed8dc9099ad523ca1e7be12355
Author: Volker Lendecke <vl at samba.org>
Date: Sat Mar 21 10:17:24 2009 +0100
Add a basic Doxyfile for talloc
-----------------------------------------------------------------------
Summary of changes:
lib/talloc/Doxyfile | 8 +
lib/talloc/talloc.h | 1041 ++++++++++++++++++++++++++++++++++++++++++-
lib/talloc/talloc_guide.txt | 694 ----------------------------
3 files changed, 1048 insertions(+), 695 deletions(-)
create mode 100644 lib/talloc/Doxyfile
delete mode 100644 lib/talloc/talloc_guide.txt
Changeset truncated at 500 lines:
diff --git a/lib/talloc/Doxyfile b/lib/talloc/Doxyfile
new file mode 100644
index 0000000..0ccf563
--- /dev/null
+++ b/lib/talloc/Doxyfile
@@ -0,0 +1,8 @@
+OUTPUT_DIRECTORY = doc
+PROJECT_NAME = Talloc
+OPTIMIZE_OUTPUT_FOR_C = YES
+GENERATE_LATEX = NO
+GENERATE_MAN = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+PREDEFINED = PRINTF_ATTRIBUTE(x,y)=
diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h
index 5c8d5c5..4adc67b 100644
--- a/lib/talloc/talloc.h
+++ b/lib/talloc/talloc.h
@@ -29,7 +29,134 @@
#include <stdio.h>
#include <stdarg.h>
-/* this is only needed for compatibility with the old talloc */
+/** \mainpage
+ *
+ * \section intro_sec Introduction
+ *
+ * Talloc is a hierarchical, reference counted memory pool system with
+ * destructors. Quite a mouthful really, but not too bad once you get used to
+ * it.
+ *
+ * Perhaps the biggest difference from other memory pool systems is that there
+ * is no distinction between a "talloc context" and a "talloc pointer". Any
+ * pointer returned from talloc() is itself a valid talloc context. This means
+ * you can do this:
+ *
+ * \code
+ * struct foo *X = talloc(mem_ctx, struct foo);
+ * X->name = talloc_strdup(X, "foo");
+ * \endcode
+ *
+ * and the pointer X->name would be a "child" of the talloc context "X" which
+ * is itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is
+ * all destroyed, whereas if you do talloc_free(X) then just X and X->name are
+ * destroyed, and if you do talloc_free(X->name) then just the name element of
+ * X is destroyed.
+ *
+ * If you think about this, then what this effectively gives you is an n-ary
+ * tree, where you can free any part of the tree with talloc_free().
+ *
+ * To start, you should probably first look at the definitions of
+ * ::TALLOC_CTX, talloc_init(), talloc() and talloc_free().
+ *
+ * \section named_blocks Named blocks
+ *
+ * Every talloc chunk has a name that can be used as a dynamic type-checking
+ * system. If for some reason like a callback function you had to cast a
+ * "struct foo *" to a "void *" variable, later you can safely reassign the
+ * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
+ * talloc_get_type_abort() macros.
+ *
+ * \code
+ * struct foo *X = talloc_get_type_abort(ptr, struct foo);
+ * \endcode
+ *
+ * This will abort if "ptr" does not contain a pointer that has been created
+ * with talloc(mem_ctx, struct foo).
+ *
+ * \section multi_threading Multi-Threading
+ *
+ * talloc itself does not deal with threads. It is thread-safe (assuming the
+ * underlying "malloc" is), as long as each thread uses different memory
+ * contexts.
+ *
+ * If two threads uses the same context then they need to synchronize in order
+ * to be safe. In particular:
+ *
+ *
+ * - when using talloc_enable_leak_report(), giving directly NULL as a
+ * parent context implicitly refers to a hidden "null context" global
+ * variable, so this should not be used in a multi-threaded environment
+ * without proper synchronization
+ * - the context returned by talloc_autofree_context() is also global so
+ * shouldn't be used by several threads simultaneously without
+ * synchronization.
+ */
+
+/** \defgroup talloc_basic Basic Talloc Routines
+ *
+ * This module contains the basic talloc routines that are used in everyday
+ * programming.
+ */
+
+/**
+ * \defgroup talloc_ref Talloc References
+ *
+ * This module contains the definitions around talloc references
+ */
+
+/**
+ * \defgroup talloc_array Array routines
+ *
+ * Talloc contains some handy helpers for handling Arrays conveniently
+ */
+
+/**
+ * \defgroup talloc_string String handling routines
+ *
+ * Talloc contains some handy string handling functions
+ */
+
+/**
+ * \defgroup talloc_debug Debugging support routines
+ *
+ * To aid memory debugging, talloc contains routines to inspect the currently
+ * allocated memory hierarchy.
+ */
+
+/**
+ * \defgroup talloc_undoc Default group of undocumented stuff
+ *
+ * This should be empty...
+ */
+
+/*\{*/
+
+/**
+ * \typedef TALLOC_CTX
+ * \brief Define a talloc parent type
+ * \ingroup talloc_basic
+ *
+ * As talloc is a hierarchial memory allocator, every talloc chunk is a
+ * potential parent to other talloc chunks. So defining a separate type for a
+ * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless,
+ * as it provides an indicator for function arguments. You will frequently
+ * write code like
+ *
+ * \code
+ * struct foo *foo_create(TALLOC_CTX *mem_ctx)
+ * {
+ * struct foo *result;
+ * result = talloc(mem_ctx, struct foo);
+ * if (result == NULL) return NULL;
+ * ... initialize foo ...
+ * return result;
+ * }
+ * \endcode
+ *
+ * In this type of allocating functions it is handy to have a general
+ * TALLOC_CTX type to indicate which parent to put allocated structures on.
+ */
typedef void TALLOC_CTX;
/*
@@ -58,6 +185,62 @@ typedef void TALLOC_CTX;
#endif
#endif
+/**
+ * \def talloc_set_destructor
+ * \brief Assign a function to be called when a chunk is freed
+ * \param ptr The talloc chunk to add a destructor to
+ * \param function The destructor function to be called
+ * \ingroup talloc_basic
+ *
+ * The function talloc_set_destructor() sets the "destructor" for the pointer
+ * "ptr". A destructor is a function that is called when the memory used by a
+ * pointer is about to be released. The destructor receives the pointer as an
+ * argument, and should return 0 for success and -1 for failure.
+ *
+ * The destructor can do anything it wants to, including freeing other pieces
+ * of memory. A common use for destructors is to clean up operating system
+ * resources (such as open file descriptors) contained in the structure the
+ * destructor is placed on.
+ *
+ * You can only place one destructor on a pointer. If you need more than one
+ * destructor then you can create a zero-length child of the pointer and place
+ * an additional destructor on that.
+ *
+ * To remove a destructor call talloc_set_destructor() with NULL for the
+ * destructor.
+ *
+ * If your destructor attempts to talloc_free() the pointer that it is the
+ * destructor for then talloc_free() will return -1 and the free will be
+ * ignored. This would be a pointless operation anyway, as the destructor is
+ * only called when the memory is just about to go away.
+ */
+
+/**
+ * \def talloc_steal(ctx, ptr)
+ * \brief Change a talloc chunk's parent
+ * \param ctx The new parent context
+ * \param ptr The talloc chunk to move
+ * \return ptr
+ * \ingroup talloc_basic
+ *
+ * The talloc_steal() function changes the parent context of a talloc
+ * pointer. It is typically used when the context that the pointer is
+ * currently a child of is going to be freed and you wish to keep the
+ * memory for a longer time.
+ *
+ * The talloc_steal() function returns the pointer that you pass it. It
+ * does not have any failure modes.
+ *
+ * NOTE: It is possible to produce loops in the parent/child relationship
+ * if you are not careful with talloc_steal(). No guarantees are provided
+ * as to your sanity or the safety of your data if you do this.
+ *
+ * To make the changed hierarchy less error-prone, you might consider to use
+ * talloc_move().
+ *
+ * talloc_steal (ctx, NULL) will return NULL with no sideeffects.
+ */
+
/* try to make talloc_set_destructor() and talloc_steal() type safe,
if we have a recent gcc */
#if (__GNUC__ >= 3)
@@ -77,34 +260,359 @@ typedef void TALLOC_CTX;
#define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
#endif
+/**
+ * \def talloc_reference(ctx, ptr)
+ * \brief Create an additional talloc parent to a pointer
+ * \param ctx The additional parent
+ * \param ptr The pointer you want to create an additional parent for
+ * \return ptr
+ * \ingroup talloc_ref
+ *
+ * The talloc_reference() function makes "context" an additional parent of
+ * "ptr".
+ *
+ * The return value of talloc_reference() is always the original pointer
+ * "ptr", unless talloc ran out of memory in creating the reference in which
+ * case it will return NULL (each additional reference consumes around 48
+ * bytes of memory on intel x86 platforms).
+ *
+ * If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
+ *
+ * After creating a reference you can free it in one of the following ways:
+ *
+ * - you can talloc_free() any parent of the original pointer. That
+ * will reduce the number of parents of this pointer by 1, and will
+ * cause this pointer to be freed if it runs out of parents.
+ *
+ * - you can talloc_free() the pointer itself. That will destroy the
+ * most recently established parent to the pointer and leave the
+ * pointer as a child of its current parent.
+ *
+ * For more control on which parent to remove, see talloc_unlink()
+ */
#define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
+
+
+/**
+ * \def talloc_move(ctx, ptr)
+ * \brief Change a talloc chunk's parent
+ * \param ctx The new parent context
+ * \param ptr Pointer to the talloc chunk to move
+ * \return ptr
+ * \ingroup talloc_basic
+ *
+ * talloc_move() has the same effect as talloc_steal(), and additionally sets
+ * the source pointer to NULL. You would use it like this:
+ *
+ * \code
+ * struct foo *X = talloc(tmp_ctx, struct foo);
+ * struct foo *Y;
+ * Y = talloc_move(new_ctx, &X);
+ * \endcode
+ */
#define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
/* useful macros for creating type checked pointers */
+
+/**
+ * \def talloc(ctx, type)
+ * \brief Main entry point to allocate structures
+ * \param ctx The talloc context to hang the result off
+ * \param type The type that we want to allocate
+ * \return Pointer to a piece of memory, properly cast to "type *"
+ * \ingroup talloc_basic
+ *
+ * The talloc() macro is the core of the talloc library. It takes a memory
+ * context and a type, and returns a pointer to a new area of memory of the
+ * given type.
+ *
+ * The returned pointer is itself a talloc context, so you can use it as the
+ * context argument to more calls to talloc if you wish.
+ *
+ * The returned pointer is a "child" of the supplied context. This means that
+ * if you talloc_free() the context then the new child disappears as
+ * well. Alternatively you can free just the child.
+ *
+ * The context argument to talloc() can be NULL, in which case a new top
+ * level context is created.
+ */
#define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
+
+/**
+ * \def talloc_size(ctx, size)
+ * \brief Untyped allocation
+ * \param ctx The talloc context to hang the result off
+ * \param size Number of char's that you want to allocate
+ * \return The allocated memory chunk
+ * \ingroup talloc_basic
+ *
+ * The function talloc_size() should be used when you don't have a convenient
+ * type to pass to talloc(). Unlike talloc(), it is not type safe (as it
+ * returns a void *), so you are on your own for type checking.
+ */
#define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
+
+/**
+ * \def talloc_ptrtype(ctx, ptr)
+ * \brief Allocate into a typed pointer
+ * \param ctx The talloc context to hang the result off
+ * \param ptr The pointer you want to assign the result to
+ * \result The allocated memory chunk, properly cast
+ * \ingroup talloc_basic
+ *
+ * The talloc_ptrtype() macro should be used when you have a pointer and
+ * want to allocate memory to point at with this pointer. When compiling
+ * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
+ * and talloc_get_name() will return the current location in the source file.
+ * and not the type.
+ */
#define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
+/**
+ * \def talloc_new(ctx)
+ * \brief Allocate a new 0-sized talloc chunk
+ * \param ctx The talloc parent context
+ * \return A new talloc chunk
+ * \ingroup talloc_basic
+ *
+ * This is a utility macro that creates a new memory context hanging off an
+ * exiting context, automatically naming it "talloc_new: __location__" where
+ * __location__ is the source line it is called from. It is particularly
+ * useful for creating a new temporary working context.
+ */
#define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
+/**
+ * \def talloc_zero(ctx, type)
+ * \brief Allocate a 0-initizialized structure
+ * \param ctx The talloc context to hang the result off
+ * \param type The type that we want to allocate
+ * \return Pointer to a piece of memory, properly cast to "type *"
+ * \ingroup talloc_basic
+ *
+ * The talloc_zero() macro is equivalent to:
+ *
+ * \code
+ * ptr = talloc(ctx, type);
+ * if (ptr) memset(ptr, 0, sizeof(type));
+ * \endcode
+ */
#define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
+
+/**
+ * \def talloc_zero_size(ctx, size)
+ * \brief Untyped, 0-initialized allocation
+ * \param ctx The talloc context to hang the result off
+ * \param size Number of char's that you want to allocate
+ * \return The allocated memory chunk
+ * \ingroup talloc_basic
+ *
+ * The talloc_zero_size() macro is equivalent to:
+ *
+ * \code
+ * ptr = talloc_size(ctx, size);
+ * if (ptr) memset(ptr, 0, size);
+ * \endcode
+ */
+
#define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
#define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
+
+/**
+ * \def talloc_array(ctx, type, count)
+ * \brief Allocate an array
+ * \param ctx The talloc context to hang the result off
+ * \param type The type that we want to allocate
+ * \param count The number of "type" elements you want to allocate
+ * \return The allocated result, properly cast to "type *"
+ * \ingroup talloc_array
+ *
+ * The talloc_array() macro is equivalent to::
+ *
+ * \code
+ * (type *)talloc_size(ctx, sizeof(type) * count);
+ * \endcode
+ *
+ * except that it provides integer overflow protection for the multiply,
+ * returning NULL if the multiply overflows.
+ */
#define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
+
+/**
+ * \def talloc_array_size(ctx, size, count)
+ * \brief Allocate an array
+ * \param ctx The talloc context to hang the result off
+ * \param size The size of an array element
+ * \param count The number of "type" elements you want to allocate
+ * \return The allocated result, properly cast to "type *"
+ * \ingroup talloc_array
+ *
+ * The talloc_array_size() function is useful when the type is not
+ * known. It operates in the same way as talloc_array(), but takes a size
+ * instead of a type.
+ */
#define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
+
+/**
+ * \def talloc_array_ptrtype(ctx, ptr, count)
+ * \brief Allocate an array into a typed pointer
+ * \param ctx The talloc context to hang the result off
+ * \param ptr The pointer you want to assign the result to
+ * \param count The number of elements you want to allocate
+ * \result The allocated memory chunk, properly cast
+ * \ingroup talloc_array
+ *
+ * The talloc_array_ptrtype() macro should be used when you have a pointer to
+ * an array and want to allocate memory of an array to point at with this
+ * pointer. When compiling with gcc >= 3 it is typesafe. Note this is a
+ * wrapper of talloc_array_size() and talloc_get_name() will return the
+ * current location in the source file. and not the type.
+ */
#define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
+
+/**
+ * \def talloc_array_length(ctx)
+ * \brief Return the number of elements in a talloc'ed array
+ * \param ctx The talloc'ed array
+ * \return The number of elements in ctx
+ * \ingroup talloc_array
+ *
+ * A talloc chunk carries its own size, so for talloc'ed arrays it is not
+ * necessary to store the number of elements explicitly.
+ */
#define talloc_array_length(ctx) ((ctx) ? talloc_get_size(ctx)/sizeof(*ctx) : 0)
+/**
+ * \def talloc_realloc(ctx, p, type, count)
+ * \brief Change the size of a talloc array
+ * \param ctx The parent context used if "p" is NULL
+ * \param p The chunk to be resized
+ * \param type The type of the array element inside p
+ * \param count The intended number of array elements
+ * \return The new array
+ * \ingroup talloc_array
+ *
+ * The talloc_realloc() macro changes the size of a talloc
+ * pointer. The "count" argument is the number of elements of type "type"
+ * that you want the resulting pointer to hold.
+ *
+ * talloc_realloc() has the following equivalences::
+ *
+ * \code
+ * talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
+ * talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
+ * talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr);
+ * \endcode
+ *
+ * The "context" argument is only used if "ptr" is NULL, otherwise it is
+ * ignored.
+ *
+ * talloc_realloc() returns the new pointer, or NULL on failure. The call
+ * will fail either due to a lack of memory, or because the pointer has
+ * more than one parent (see talloc_reference()).
+ */
#define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
+
+/**
+ * \def talloc_realloc_size(ctx, ptr, size)
+ * \brief Untyped realloc
+ * \param ctx The parent context used if "ptr" is NULL
+ * \param ptr The chunk to be resized
+ * \param size The new chunk size
+ * \return The new chunk
+ * \ingroup talloc_array
+ *
+ * The talloc_realloc_size() function is useful when the type is not known so
+ * the typesafe talloc_realloc() cannot be used.
+ */
#define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
+/**
+ * \def talloc_memdup(t, p, size)
+ * \brief Duplicate a memory area into a talloc chunk
+ * \param t The talloc context to hang the result off
+ * \param p The memory chunk you want to duplicate
+ * \param size Number of char's that you want copy
+ * \return The allocated memory chunk
+ * \ingroup talloc_basic
+ *
+ * The talloc_memdup() function is equivalent to::
+ *
--
Samba Shared Repository
More information about the samba-cvs
mailing list