diff options
author | Andrew Tridgell <tridge@samba.org> | 2004-10-03 00:04:30 +0000 |
---|---|---|
committer | Gerald (Jerry) Carter <jerry@samba.org> | 2007-10-10 12:59:34 -0500 |
commit | 15b9736ed30d8e947dbe2513dd9cf27d5b3761af (patch) | |
tree | 1b5ab1fbdf06e67b67eb8452eac970aac80fe4ad /talloc_guide.txt | |
parent | a248164de5f89cef824f5a1f7d8618fbe81ae0c4 (diff) | |
download | samba-15b9736ed30d8e947dbe2513dd9cf27d5b3761af.tar.gz samba-15b9736ed30d8e947dbe2513dd9cf27d5b3761af.tar.bz2 samba-15b9736ed30d8e947dbe2513dd9cf27d5b3761af.zip |
r2791: got rid of talloc_unreference() and instead created talloc_unlink(),
which is much clearer and simpler to use. It removes a specific parent
from a pointer, no matter whether that parent is a "reference" or a
direct parent. This gives complete control over the free process.
(This used to be commit 6c563887f1b9b8c842309a523e88b6f2a32db10f)
Diffstat (limited to 'talloc_guide.txt')
-rw-r--r-- | talloc_guide.txt | 36 |
1 files changed, 19 insertions, 17 deletions
diff --git a/talloc_guide.txt b/talloc_guide.txt index b61e08e708..7742ade623 100644 --- a/talloc_guide.txt +++ b/talloc_guide.txt @@ -33,10 +33,9 @@ n-ary tree, where you can free any part of the tree with talloc_free(). If you find this confusing, then I suggest you run the LOCAL-TALLOC -smbtorture test with the --leak-report-full option to watch talloc in -action. You may also like to add your own tests to -source/torture/local/talloc.c to clarify how some particular situation -is handled. +smbtorture test to watch talloc in action. You may also like to add +your own tests to source/torture/local/talloc.c to clarify how some +particular situation is handled. Performance @@ -103,9 +102,11 @@ destructor returned -1. See talloc_set_destructor() for details on destructors. If this pointer has an additional reference when talloc_free() is -called then the memory is not actually released, but instead the -reference is destroyed. See talloc_reference() for details on -establishing additional references. +called then the memory is not actually released, but instead the most +recently established reference is destroyed. See talloc_reference() +for details on establishing additional references. + +For more control on which parent is removed, see talloc_unlink() talloc_free() operates recursively on its children. @@ -137,21 +138,22 @@ ways: reference. That will destroy the reference, and leave the pointer where it is. +For more control on which parent to remove, see talloc_unlink() + =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_unreference(const void *context, const void *ptr); +int talloc_unlink(const void *context, const void *ptr); -The talloc_unreference() function removes a reference added by -talloc_reference(). It must be called with exactly the same arguments -as talloc_reference(). +The talloc_unlink() function removes a specific parent from ptr. The +context passed must either be a context used in talloc_reference() +with this pointer, or must be a direct parent of ptr. -Note that if the reference has already been removed using -talloc_free() then this function will fail and will return NULL. +Note that if the parent has already been removed using talloc_free() +then this function will fail and will return -1. -Usually you can just use talloc_free() instead of -talloc_unreference(), but sometimes it is useful to have the -additional control on who becomes the parent of the pointer given by -talloc_unreference(). +Usually you can just use talloc_free() instead of talloc_unlink(), but +sometimes it is useful to have the additional control on which parent +is removed. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- |