libtalloc_tutorial(3) [centos man page]

libtalloc_tutorial(3)						      talloc						     libtalloc_tutorial(3)

NAME

       libtalloc_tutorial - The Tutorial

Introduction
       Talloc is a hierarchical, reference counted memory pool system with destructors. It is built atop the C standard library and it defines a
       set of utility functions that altogether simplifies allocation and deallocation of data, especially for complex structures that contain
       many dynamically allocated elements such as strings and arrays.

       The main goals of this library are: removing the needs for creating a cleanup function for every complex structure, providing a logical
       organization of allocated memory blocks and reducing the likelihood of creating memory leaks in long-running applications. All of this is
       achieved by allocating memory in a hierarchical structure of talloc contexts such that deallocating one context recursively frees all of
       its descendants as well.

Main features
       o An open source project

       o A hierarchical memory model

       o Natural projection of data structures into the memory space

       o Simplifies memory management of large data structures

       o Automatic execution of a destructor before the memory is freed

       o Simulates a dynamic type system

       o Implements a transparent memory pool

Table of contents:
       Chapter 1: Talloc context

       Chapter 2: Stealing a context

       Chapter 3: Dynamic type system

       Chapter 4: Using destructors

       Chapter 5: Memory pools

       Chapter 6: Debugging

       Chapter 7: Best practises

Version 2.0							  Tue Jun 17 2014					     libtalloc_tutorial(3)

libtalloc_destructors(3)					      talloc						  libtalloc_destructors(3)

NAME

       libtalloc_destructors - Chapter 4: Using destructors

Using destructors
       Destructors are well known methods in the world of object oriented programming. A destructor is a method of an object that is automatically
       run when the object is destroyed. It is usually used to return resources taken by the object back to the system (e.g. closing file
       descriptors, terminating connection to a database, deallocating memory).

       With talloc we can take the advantage of destructors even in C. We can easily attach our own destructor to a talloc context. When the
       context is freed, the destructor will run automatically.

       To attach/detach a destructor to a talloc context use: talloc_set_destructor().

Example
       Imagine that we have a dynamically created linked list. Before we deallocate an element of the list, we need to make sure that we have
       successfully removed it from the list. Normally, this would be done by two commands in the exact order: remove it from the list and then
       free the element. With talloc, we can do this at once by setting a destructor on the element which will remove it from the list and
       talloc_free() will do the rest.

       The destructor would be:

       int list_remove(void *ctx)
       {
	   struct list_el *el = NULL;
	   el = talloc_get_type_abort(ctx, struct list_el);
	   /* remove element from the list */
       }

       GCC version 3 and newer can check for the types during the compilation. So if it is our major compiler, we can use a more advanced
       destructor:

       int list_remove(struct list_el *el)
       {
	   /* remove element from the list */
       }

       Now we will assign the destructor to the list element. We can do this directly in the function that inserts it.

       struct list_el* list_insert(TALLOC_CTX *mem_ctx,
				   struct list_el *where,
				   void *ptr)
       {
	 struct list_el *el = talloc(mem_ctx, struct list_el);
	 el->data = ptr;
	 /* insert into list */

	 talloc_set_destructor(el, list_remove);
	 return el;
       }

       Because talloc is a hierarchical memory allocator, we can go a step further and free the data with the element as well:

       struct list_el* list_insert_free(TALLOC_CTX *mem_ctx,
					struct list_el *where,
					void *ptr)
       {
	 struct list_el *el = NULL;
	 el = list_insert(mem_ctx, where, ptr);

	 talloc_steal(el, ptr);

	 return el;
       }

Version 2.0							  Tue Jun 17 2014					  libtalloc_destructors(3)