mpv/ta/README

TA ("Tree Allocator") is a wrapper around malloc() and related functions,
adding features like automatically free sub-trees of memory allocations if
a parent allocation is freed.

Generally, the idea is that every TA allocation can have a parent (indicated
by the ta_parent argument in allocation function calls). If a parent is freed,
its child allocations are automatically freed as well. It's also allowed the
free a child before the parent, or to move a child to another parent with
ta_set_parent().

It also provides a bunch of convenience macros and debugging facilities.

The TA functions are documented in the implementation files (ta.c, ta_utils.c).

TA is intended to be useable as library independent from mpv. It doesn't
depend on anything mpv specific.

Note:
-----

mpv doesn't use the TA API yet for two reasons: first, the TA API is not
necessarily finalized yet. Second, it should be easily possible to revert
the commit adding TA, and changing all the code would not allow this.

Especially the naming schema for some TA functions is still somewhat
undecided. (The talloc naming is a bit verbose at times.)

For now, mpv goes through a talloc wrapper, which maps the talloc API to TA.
New code should still use talloc as well. At one point, all talloc calls
will be replaced with TA calls, and the talloc wrapper will be removed.

Documentation for the talloc API is here:

    http://git.samba.org/?p=samba.git;a=blob;f=lib/talloc/talloc.h;hb=HEAD

There are some minor differences with mpv's talloc bridge. mpv calls abort()
on allocation failures, and the talloc_set_destructor() signature is slightly
different. libtalloc also has a weird 256MB limit per allocation. The talloc
wrapper supports only a strict subset of libtalloc functionality used by mpv.
Replace talloc There are multiple reasons to do this. One big reason is the license: talloc is LGPLv3+, which forces mpv to be licensed as GPLv3+. Another one is that our talloc copy contains modifications, which makes it essentially incompatible with upstream talloc (in particular, our version aborts on out of memory conditions - well, it wasn't my idea). Updating from upstream is also a bit involved - the talloc source is not really organized in a way to allow copying it into projects (and this isn't an intended use-case). Finally, talloc is kind of big and bloated. The replacement halves the amount of code - mainly because we didn't use all talloc features. It's even more extreme if you compare upstream talloc (~4700 lines) and the new allocator without talloc compat (~900 lines). The replacement provides all features we need. It also doesn't clash with talloc. (The talloc compatibility wrapper uses macros to avoid introducing linker-level symbols which could clash with libtalloc.) It also tries to lower the overhead (only 4 words opposed to 10 words in talloc for leaf nodes in release mode). Debugging features like leak reporting can be enabled at compile time and add somewhat more overhead. Though I'm not sure whether the overhead reduction was actually successful: allocations with children need an "extra" header, which adds plenty of overhead, and it turns out that almost half of all allocations have children. Maybe the implementation could be simplified and the extra header removed - even then, overhead would be lower than talloc's. Currently, debugging features can be entirely deactivated by defining NDEBUG - I'm not sure if anything defines this directly yet, though. Unlike in talloc, the leak reporting stuff is thread-safe. (That's also why it's far less elegant, and requires extra list pointers.) Comes with a compatibility layer, so no changes to mpv source code are needed. The idea is that we will pretend to be using talloc for a while, so that we can revert to our old talloc implementation at any time for debugging purposes. Some inspiration was taken from Mesa's ralloc: http://cgit.freedesktop.org/mesa/mesa/tree/src/glsl/ralloc.h This is another talloc replacement, but lacks some features we need (getting size of an allocation, debugging features, being able to access children in the dtor). There's some information in ta/README what will happen next and how the transition is expected to progress. 2013-10-12 23:17:45 +00:00			`TA ("Tree Allocator") is a wrapper around malloc() and related functions,`
			`adding features like automatically free sub-trees of memory allocations if`
			`a parent allocation is freed.`

			`Generally, the idea is that every TA allocation can have a parent (indicated`
			`by the ta_parent argument in allocation function calls). If a parent is freed,`
			`its child allocations are automatically freed as well. It's also allowed the`
			`free a child before the parent, or to move a child to another parent with`
			`ta_set_parent().`

			`It also provides a bunch of convenience macros and debugging facilities.`

			`The TA functions are documented in the implementation files (ta.c, ta_utils.c).`

			`TA is intended to be useable as library independent from mpv. It doesn't`
			`depend on anything mpv specific.`

			`Note:`
			`-----`

			`mpv doesn't use the TA API yet for two reasons: first, the TA API is not`
			`necessarily finalized yet. Second, it should be easily possible to revert`
			`the commit adding TA, and changing all the code would not allow this.`

			`Especially the naming schema for some TA functions is still somewhat`
			`undecided. (The talloc naming is a bit verbose at times.)`

			`For now, mpv goes through a talloc wrapper, which maps the talloc API to TA.`
			`New code should still use talloc as well. At one point, all talloc calls`
			`will be replaced with TA calls, and the talloc wrapper will be removed.`

			`Documentation for the talloc API is here:`

			`http://git.samba.org/?p=samba.git;a=blob;f=lib/talloc/talloc.h;hb=HEAD`

			`There are some minor differences with mpv's talloc bridge. mpv calls abort()`
			`on allocation failures, and the talloc_set_destructor() signature is slightly`
			`different. libtalloc also has a weird 256MB limit per allocation. The talloc`
			`wrapper supports only a strict subset of libtalloc functionality used by mpv.`