diff options
Diffstat (limited to 'ctdb/lib/talloc/talloc.3.xml')
| -rw-r--r-- | ctdb/lib/talloc/talloc.3.xml | 84 |
1 files changed, 79 insertions, 5 deletions
diff --git a/ctdb/lib/talloc/talloc.3.xml b/ctdb/lib/talloc/talloc.3.xml index 67de15bfc8b..bc1676df50c 100644 --- a/ctdb/lib/talloc/talloc.3.xml +++ b/ctdb/lib/talloc/talloc.3.xml @@ -135,6 +135,30 @@ <para> talloc_free() operates recursively on its children. </para> + <para> + From the 2.0 version of talloc, as a special case, + talloc_free() is refused on pointers that have more than one + parent, as talloc would have no way of knowing which parent + should be removed. To free a pointer that has more than one + parent please use talloc_unlink(). + </para> + <para> + To help you find problems in your code caused by this behaviour, if + you do try and free a pointer with more than one parent then the + talloc logging function will be called to give output like this: + </para> + <para> + <screen format="linespecific"> + ERROR: talloc_free with references at some_dir/source/foo.c:123 + reference at some_dir/source/other.c:325 + reference at some_dir/source/third.c:121 + </screen> + </para> + <para> + Please see the documentation for talloc_set_log_fn() and + talloc_set_log_stderr() for more information on talloc logging + functions. + </para> </refsect2> <refsect2 id="talloc_reference"><title>void *talloc_reference(const void *ctx, const void *ptr);</title> <para> @@ -338,7 +362,7 @@ talloc_set_name_const(ptr, name);</programlisting> <refsect2><title>void *talloc_new(void *<emphasis role="italic">ctx</emphasis>);</title> <para> This is a utility macro that creates a new memory context hanging - off an exiting context, automatically naming it "talloc_new: + off an existing 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. @@ -381,11 +405,49 @@ talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);</programlisting> It does not have any failure modes. </para> <para> - NOTE: It is possible to produce loops in the parent/child + 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. </para> + <para> + Note that if you try and call talloc_steal() on a pointer that has + more than one parent then the result is ambiguous. Talloc will choose + to remove the parent that is currently indicated by talloc_parent() + and replace it with the chosen parent. You will also get a message + like this via the talloc logging functions: + </para> + <para> + <screen format="linespecific"> + WARNING: talloc_steal with references at some_dir/source/foo.c:123 + reference at some_dir/source/other.c:325 + reference at some_dir/source/third.c:121 + </screen> + </para> + <para> + To unambiguously change the parent of a pointer please see + the + function <link linkend="talloc_reference"><quote>talloc_reparent()</quote></link>. See + the talloc_set_log_fn() documentation for more information + on talloc logging. + </para> + </refsect2> + <refsect2><title>TYPE *talloc_reparent(const void *<emphasis role="italic">old_parent</emphasis>, const void *<emphasis role="italic">new_parent</emphasis>, const TYPE *<emphasis role="italic">ptr</emphasis>);</title> + <para> + The talloc_reparent() 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. + </para> + <para> + The talloc_reparent() function returns the pointer that you pass it. It + does not have any failure modes. + </para> + <para> + The difference between talloc_reparent() and talloc_steal() is that + talloc_reparent() can specify which parent you wish to change. This is + useful when a pointer has multiple parents via references. + </para> </refsect2> <refsect2><title>TYPE *talloc_move(const void *<emphasis role="italic">new_ctx</emphasis>, TYPE **<emphasis role="italic">ptr</emphasis>);</title> <para> @@ -627,7 +689,7 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting> </para> <programlisting>talloc_set_name_const(ptr, ptr)</programlisting> </refsect2> - <refsect2><title>(type *)talloc_array(const void *ctx, type, uint_t count);</title> + <refsect2><title>(type *)talloc_array(const void *ctx, type, unsigned int count);</title> <para> The talloc_array() macro is equivalent to: </para> @@ -637,14 +699,14 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting> multiply, returning NULL if the multiply overflows. </para> </refsect2> - <refsect2><title>void *talloc_array_size(const void *ctx, size_t size, uint_t count);</title> + <refsect2><title>void *talloc_array_size(const void *ctx, size_t size, unsigned int count);</title> <para> 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. </para> </refsect2> - <refsect2><title>(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);</title> + <refsect2><title>(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int count);</title> <para> The talloc_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 @@ -696,6 +758,18 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting> </para> <programlisting>talloc_set_name_const(ptr, #type)</programlisting> </refsect2> + <refsect2><title>talloc_set_log_fn(void (*log_fn)(const char *message));</title> + <para> + This function sets a logging function that talloc will use for + warnings and errors. By default talloc will not print any warnings or + errors. + </para> + </refsect2> + <refsect2><title>talloc_set_log_stderr(void);</title> + <para> + This sets the talloc log function to write log messages to stderr + </para> + </refsect2> </refsect1> <refsect1><title>PERFORMANCE</title> <para> |