Revert "Document talloc_pool()"

[ira/wip.git] / lib / talloc / talloc.h

diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h
index d103d6f4f200d4a3c307fca84c37b1dc85a48b91..4adc67b7fd3f2b454a0fa61c34407eaa1b841c2b 100644 (file)
--- a/lib/talloc/talloc.h
+++ b/lib/talloc/talloc.h
@@ -124,15 +124,6 @@
  * allocated memory hierarchy.
  */
 
-/**
- * \defgroup talloc_internal Internal routines
- *
- * To achieve type-safety, talloc.h defines a lot of macros with type
- * casts. These macros define the user interface to the internal routines you
- * find here. You should not really use these routines directly but go through
- * the external API.
- */
-
 /**
  * \defgroup talloc_undoc Default group of undocumented stuff
  *
@@ -633,64 +624,10 @@ typedef void TALLOC_CTX;
 #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))
 #endif
 
-/**
- * \def TALLOC_FREE(ctx)
- * \brief talloc_free a chunk and NULL out the pointer
- * \param ctx The chunk to be freed
- * \ingroup talloc_basic
- *
- * TALLOC_FREE() frees a pointer and sets it to NULL. Use this if you want
- * immediate feedback (i.e. crash) if you use a pointer after having free'ed
- * it.
- */
 #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0)
 
-/**
- * \brief Allocate untyped, unnamed memory
- * \param context 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_internal
- *
- * Essentially the same as talloc_size() without setting the chunk name to the
- * current file/line number.
- */
+/* The following definitions come from talloc.c  */
 void *_talloc(const void *context, size_t size);
-
-/**
- * \brief Allocate a talloc pool
- * \param context The talloc context to hang the result off
- * \param size Size of the talloc pool
- * \result The talloc pool
- * \ingroup talloc_basic
- *
- * A talloc pool is a pure optimization for specific situations. In the
- * release process for Samba 3.2 we found out that we had become considerably
- * slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU
- * consumer in benchmarks. For Samba 3.2 we have internally converted many
- * static buffers to dynamically allocated ones, so malloc(3) being beaten
- * more was no surprise. But it made us slower.
- *
- * talloc_pool() is an optimization to call malloc(3) a lot less for the use
- * pattern Samba has: The SMB protocol is mainly a request/response protocol
- * where we have to allocate a certain amount of memory per request and free
- * that after the SMB reply is sent to the client.
- *
- * talloc_pool() creates a talloc chunk that you can use as a talloc parent
- * exactly as you would use any other ::TALLOC_CTX. The difference is that
- * when you talloc a child of this pool, no malloc(3) is done. Instead, talloc
- * just increments a pointer inside the talloc_pool. This also works
- * recursively. If you use the child of the talloc pool as a parent for
- * grand-children, their memory is also taken from the talloc pool.
- *
- * If you talloc_free() children of a talloc pool, the memory is not given
- * back to the system. Instead, free(3) is only called if the talloc_pool()
- * itself is released with talloc_free().
- *
- * The downside of a talloc pool is that if you talloc_move() a child of a
- * talloc pool to a talloc parent outside the pool, the whole pool memory is
- * not free(3)'ed until that moved chunk is also talloc_free()ed.
- */
 void *talloc_pool(const void *context, size_t size);
 void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));