[Xen-changelog] [xen-unstable] tools/libxl: document libxl memory management policy

[Xen patchbot-unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>]

# HG changeset patch
# User Gianni Tedesco <gianni.tedesco@xxxxxxxxxx>
# Date 1281715002 -3600
# Node ID 5decc6971f2a5ef4d72a7f52b7e4dab29c1042da
# Parent  fe21e474c6942a95fa0f86bd65e1209c6010ed33
tools/libxl: document libxl memory management policy

After animated discussion with several libxl developers we seem to have
agreed on a policy for memory management within libxenlight. These
comments document the policy which is mostly implemented since
21977:51147d5b17c3 but some aspects (comments, function naming) are
guidelines to be followed in future functionality and perhaps to be
implemented by search/replace in future patches.

The document is mostly authored by Ian Jackson but with modifications to
reflect the slightly different functionality that has been implemented
since this was proposed.

Signed-off-by: Gianni Tedesco <gianni.tedesco@xxxxxxxxxx>
Signed-off-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
---
 tools/libxl/libxl.h |  110 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 110 insertions(+)

diff -r fe21e474c694 -r 5decc6971f2a tools/libxl/libxl.h
--- a/tools/libxl/libxl.h       Fri Aug 13 14:59:03 2010 +0100
+++ b/tools/libxl/libxl.h       Fri Aug 13 16:56:42 2010 +0100
@@ -11,6 +11,116 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Lesser General Public License for more details.
+ */
+
+/*
+ * libxl memory management
+ *
+ * From the point of view of the application (ie, libxl's caller),
+ * struct libxl_ctx* is threadsafe, and all returned allocated
+ * structures are obtained from malloc(), and must be freed by the
+ * caller either directly or by calling an appropriate free function
+ * provided by libxl.  Ie the application does not get automatic
+ * assistance from libxl in managing these allocations.
+ *
+ * Specific details are in the header comments which should be found
+ * in libxl.h or libxlutil.h, next to the relevant function
+ * declarations.
+ *
+ * Internally, libxl has a garbage collection scheme which allows much libxl
+ * code to allocate strings etc. for internal use without needing to
+ * free them.  These are called "temporary allocations".
+ *
+ * The pool for these temporary allocations, along with any other
+ * thread-specific data which is private to libxl but shared between
+ * libxl functions (such as the current xenstore transaction), is
+ * stored in the "gc context" which is a special enhanced context
+ * structure allocated automatically by convenience macros at every
+ * entry to libxl.
+ *
+ * Every libxl function falls into one of these categories:
+ *
+ * 1. Public functions (declared in libxl.h, libxlutil.h), which may
+ *    be called by libxl applications.  If a public function returns
+ *    any allocated object to its caller, that object must have come
+ *    from malloc.
+ *
+ *    The definitions of public functions MUST use the gc context
+ *    initialisation macros (or do the equivalent work themselves).
+ *    These macros will ensure that all temporary allocations will be
+ *    automatically freed before the function returns to its caller.
+ *
+ *    A public function may be called from within libxl; the call
+ *    context initialisation macros will make sure that the internal
+ *    caller's context is reused (eg, so that the same xenstore
+ *    transaction is used).
+ *
+ *    Public functions have names like libxl_foobar.
+ *
+ * 2. Private functions, which may not be called by libxl
+ *    applications; they are not declared in libxl.h or libxlutil.h
+ *    and they may not be called other than by other libxl functions.
+ *
+ *    Private functions should not use the gc context initialisation
+ *    macros.
+ *
+ *    Private functions have names like libxl__foobar (NB, two underscores).
+ *    Also the declaration of such functions must be preceeded by the _hidden
+ *    macro.
+ *
+ * Allocations made by a libxl function fall into one of the following
+ * categories (where "object" includes any memory allocation):
+ *
+ * (a) Objects which are not returned to the function's caller.
+ *     These should be allocated from the temporary pool.
+ *
+ * (b) Objects which are intended for return to the calling
+ *     application.  This includes all allocated objects returned by
+ *     any public function.
+ *
+ *     It may also include objects allocated by an internal function
+ *     specifically for eventual return by the function's external
+ *     callers, but this situation should be clearly documented in
+ *     comments.
+ *
+ *     These should be allocated from malloc() et al. and comments
+ *     near the function declaration should explain the memory
+ *     ownership.  If a simple free() by the application is not
+ *     sufficient, a suitable public freeing function should be
+ *     provided.
+ *
+ * (c) Internal objects whose size and/or lifetime dictate explicit
+ *     memory management within libxl.  This includes objects which
+ *     will be embedded in opaque structures which will be returned to
+ *     the libxl caller (more generally, any internal object whose
+ *     lifetime exceeds the libxl entrypoint which creates it) and
+ *     objects which are so large or numerous that explicit memory
+ *     management is required.
+ *
+ *     These should be allocated from malloc() et al., and freed
+ *     explicitly at the appropriate point.  The situation should be
+ *     documented in comments.
+ *
+ * (d) Objects which are allocated by internal-only functions and
+ *     returned to the function's (therefore, internal) caller but are
+ *     strictly for internal use by other parts of libxl.  These
+ *     should be allocated from the temporary pool.
+ *
+ *     Where a function's primary purpose is to return such an object,
+ *     it should have a libxl_gc * as it's first argument.
+ *
+ *     Note that there are two ways to change an allocation from this
+ *     category to the "public" category. Either the implementation
+ *     is kept internal and a wrapper function duplicates all memory
+ *     allocations so that they are suitable for return to external
+ *     callers or the implementation uses plain malloc() et al calls
+ *     and an internal wrapper adds the relevant pointers to the gc.
+ *     The latter method is preferred for obvious performance reasons.
+ *
+ * No temporary objects allocated from the pool should be explicitly freed.
+ * Calling libxl_free_all() before returning from a public functions will do
+ * this. The upshot of this is that almost all calls to libxl_free() are
+ * erroneous.
  */
 #ifndef LIBXL_H
 #define LIBXL_H

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog