WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-changelog

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

To: xen-changelog@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-changelog] [xen-unstable] tools/libxl: document libxl memory management policy
From: Xen patchbot-unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>
Date: Wed, 18 Aug 2010 07:00:47 -0700
Delivery-date: Wed, 18 Aug 2010 07:04:35 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-changelog-request@lists.xensource.com?subject=help>
List-id: BK change log <xen-changelog.lists.xensource.com>
List-post: <mailto:xen-changelog@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-changelog>, <mailto:xen-changelog-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-changelog>, <mailto:xen-changelog-request@lists.xensource.com?subject=unsubscribe>
Reply-to: xen-devel@xxxxxxxxxxxxxxxxxxx
Sender: xen-changelog-bounces@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

<Prev in Thread] Current Thread [Next in Thread>
  • [Xen-changelog] [xen-unstable] tools/libxl: document libxl memory management policy, Xen patchbot-unstable <=