1.1 --- a/tools/libxl/libxl.h	Fri Aug 13 14:59:03 2010 +0100
     1.2 +++ b/tools/libxl/libxl.h	Fri Aug 13 16:56:42 2010 +0100
     1.3 @@ -12,6 +12,116 @@
     1.4   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     1.5   * GNU Lesser General Public License for more details.
     1.6   */
     1.7 +
     1.8 +/*
     1.9 + * libxl memory management
    1.10 + *
    1.11 + * From the point of view of the application (ie, libxl's caller),
    1.12 + * struct libxl_ctx* is threadsafe, and all returned allocated
    1.13 + * structures are obtained from malloc(), and must be freed by the
    1.14 + * caller either directly or by calling an appropriate free function
    1.15 + * provided by libxl.  Ie the application does not get automatic
    1.16 + * assistance from libxl in managing these allocations.
    1.17 + *
    1.18 + * Specific details are in the header comments which should be found
    1.19 + * in libxl.h or libxlutil.h, next to the relevant function
    1.20 + * declarations.
    1.21 + *
    1.22 + * Internally, libxl has a garbage collection scheme which allows much libxl
    1.23 + * code to allocate strings etc. for internal use without needing to
    1.24 + * free them.  These are called "temporary allocations".
    1.25 + *
    1.26 + * The pool for these temporary allocations, along with any other
    1.27 + * thread-specific data which is private to libxl but shared between
    1.28 + * libxl functions (such as the current xenstore transaction), is
    1.29 + * stored in the "gc context" which is a special enhanced context
    1.30 + * structure allocated automatically by convenience macros at every
    1.31 + * entry to libxl.
    1.32 + *
    1.33 + * Every libxl function falls into one of these categories:
    1.34 + *
    1.35 + * 1. Public functions (declared in libxl.h, libxlutil.h), which may
    1.36 + *    be called by libxl applications.  If a public function returns
    1.37 + *    any allocated object to its caller, that object must have come
    1.38 + *    from malloc.
    1.39 + *
    1.40 + *    The definitions of public functions MUST use the gc context
    1.41 + *    initialisation macros (or do the equivalent work themselves).
    1.42 + *    These macros will ensure that all temporary allocations will be
    1.43 + *    automatically freed before the function returns to its caller.
    1.44 + *
    1.45 + *    A public function may be called from within libxl; the call
    1.46 + *    context initialisation macros will make sure that the internal
    1.47 + *    caller's context is reused (eg, so that the same xenstore
    1.48 + *    transaction is used).
    1.49 + *
    1.50 + *    Public functions have names like libxl_foobar.
    1.51 + *
    1.52 + * 2. Private functions, which may not be called by libxl
    1.53 + *    applications; they are not declared in libxl.h or libxlutil.h
    1.54 + *    and they may not be called other than by other libxl functions.
    1.55 + *
    1.56 + *    Private functions should not use the gc context initialisation
    1.57 + *    macros.
    1.58 + *
    1.59 + *    Private functions have names like libxl__foobar (NB, two underscores).
    1.60 + *    Also the declaration of such functions must be preceeded by the _hidden
    1.61 + *    macro.
    1.62 + *
    1.63 + * Allocations made by a libxl function fall into one of the following
    1.64 + * categories (where "object" includes any memory allocation):
    1.65 + *
    1.66 + * (a) Objects which are not returned to the function's caller.
    1.67 + *     These should be allocated from the temporary pool.
    1.68 + *
    1.69 + * (b) Objects which are intended for return to the calling
    1.70 + *     application.  This includes all allocated objects returned by
    1.71 + *     any public function.
    1.72 + *
    1.73 + *     It may also include objects allocated by an internal function
    1.74 + *     specifically for eventual return by the function's external
    1.75 + *     callers, but this situation should be clearly documented in
    1.76 + *     comments.
    1.77 + *
    1.78 + *     These should be allocated from malloc() et al. and comments
    1.79 + *     near the function declaration should explain the memory
    1.80 + *     ownership.  If a simple free() by the application is not
    1.81 + *     sufficient, a suitable public freeing function should be
    1.82 + *     provided.
    1.83 + *
    1.84 + * (c) Internal objects whose size and/or lifetime dictate explicit
    1.85 + *     memory management within libxl.  This includes objects which
    1.86 + *     will be embedded in opaque structures which will be returned to
    1.87 + *     the libxl caller (more generally, any internal object whose
    1.88 + *     lifetime exceeds the libxl entrypoint which creates it) and
    1.89 + *     objects which are so large or numerous that explicit memory
    1.90 + *     management is required.
    1.91 + *
    1.92 + *     These should be allocated from malloc() et al., and freed
    1.93 + *     explicitly at the appropriate point.  The situation should be
    1.94 + *     documented in comments.
    1.95 + *
    1.96 + * (d) Objects which are allocated by internal-only functions and
    1.97 + *     returned to the function's (therefore, internal) caller but are
    1.98 + *     strictly for internal use by other parts of libxl.  These
    1.99 + *     should be allocated from the temporary pool.
   1.100 + *
   1.101 + *     Where a function's primary purpose is to return such an object,
   1.102 + *     it should have a libxl_gc * as it's first argument.
   1.103 + *
   1.104 + *     Note that there are two ways to change an allocation from this
   1.105 + *     category to the "public" category. Either the implementation
   1.106 + *     is kept internal and a wrapper function duplicates all memory
   1.107 + *     allocations so that they are suitable for return to external
   1.108 + *     callers or the implementation uses plain malloc() et al calls
   1.109 + *     and an internal wrapper adds the relevant pointers to the gc.
   1.110 + *     The latter method is preferred for obvious performance reasons.
   1.111 + *
   1.112 + * No temporary objects allocated from the pool should be explicitly freed.
   1.113 + * Calling libxl_free_all() before returning from a public functions will do
   1.114 + * this. The upshot of this is that almost all calls to libxl_free() are
   1.115 + * erroneous.
   1.116 + */
   1.117  #ifndef LIBXL_H
   1.118  #define LIBXL_H
   1.119