samba-4.9.2.tar.gz

Using talloc in Samba4 ====================== .. contents:: Andrew Tridgell August 2009 The most current version of this document is available at http://samba.org/ftp/unpacked/talloc/talloc_guide.txt If you are used to the "old" talloc from Samba3 before 3.0.20 then please read this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the Samba4 talloc has been ported back to Samba3, so this guide applies to both. The new 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 change from Samba3 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:: struct foo *X = talloc(mem_ctx, struct foo); X->name = talloc_strdup(X, "foo"); 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(). If you find this confusing, then I suggest you run the testsuite to watch talloc in action. You may also like to add your own tests to testsuite.c to clarify how some particular situation is handled. Performance ----------- All the additional features of talloc() over malloc() do come at a price. We have a simple performance test in Samba4 that measures talloc() versus malloc() performance, and it seems that talloc() is about 4% slower than malloc() on my x86 Debian Linux box. For Samba, the great reduction in code complexity that we get by using talloc makes this worthwhile, especially as the total overhead of talloc/malloc in Samba is already quite small. talloc API ---------- The following is a complete guide to the talloc API. Read it all at least twice. 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 use 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. In threaded code turn off null tracking using talloc_disable_null_tracking(). ; - the context returned by talloc_autofree_context() is also global so shouldn't be used by several threads simultaneously without synchronization. talloc and shared objects ------------------------- talloc can be used in shared objects. Special care needs to be taken to never use talloc_autofree_context() in code that might be loaded with dlopen() and unloaded with dlclose(), as talloc_autofree_context() internally uses atexit(3). Some platforms like modern Linux handles this fine, but for example FreeBSD does not deal well with dlopen() and atexit() used simultaneously: dlclose() does not clean up the list of atexit-handlers, so when the program exits the code that was registered from within talloc_autofree_context() is gone, the program crashes at exit. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- (type *)talloc(const void *context, type); 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. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- void *talloc_size(const void *context, size_t size); 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. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- (typeof(ptr)) talloc_ptrtype(const void *ctx, ptr); 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. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- int talloc_free(void *ptr); The talloc_free() function frees a piece of talloc memory, and all its children. You can call talloc_free() on any pointer returned by talloc(). The return value of talloc_free() indicates success or failure, with 0 returned for success and -1 for failure. A possible failure condition is if the pointer had a destructor attached to it and the destructor returned -1. See talloc_set_destructor() for details on destructors. Likewise, if "ptr" is NULL, then the function will make no modifications and returns -1. From version 2.0 and onwards, as a special case, talloc_free() is refused on pointers that have more than one parent associated, as talloc would have no way of knowing which parent should be removed. This is different from older versions in the sense that always the reference to the most recently established parent has been destroyed. Hence to free a pointer that has more than one parent please use talloc_unlink(). 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: 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 Please see the documentation for talloc_set_log_fn() and talloc_set_log_stderr() for more information on talloc logging functions. talloc_free() operates recursively on its children. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- void talloc_free_children(void *ptr); The talloc_free_children() walks along the list of all children of a talloc context and talloc_free()s only the children, not the context itself. A NULL argument is handled as no-op. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- void *talloc_reference(const void *context, const void *ptr); 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 if it has at maximum one parent. This behaviour has been changed since the release of version 2.0. Further informations in the description of "talloc_free". For more control on which parent to remove, see talloc_unlink() =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-