[Xen-devel] [PATCH 01 of 23] libxl: Document _init/_dispose/_setdefault functions

[Ian Campbell <ian.campbell@xxxxxxxxxx>]

# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# Date 1329147318 0
# Node ID d50c4dc752717e2742a7e9018fcbaffbfff9ea6c
# Parent  1d0bcc8cafd5abd34da13ce32758c505c73cfa48
libxl: Document _init/_dispose/_setdefault functions.

Subsequent patches will transition to them.

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

diff -r 1d0bcc8cafd5 -r d50c4dc75271 tools/libxl/libxl.h
--- a/tools/libxl/libxl.h       Mon Feb 13 15:35:18 2012 +0000
+++ b/tools/libxl/libxl.h       Mon Feb 13 15:35:18 2012 +0000
@@ -124,6 +124,54 @@
  * Therefore public functions which initialize a libxl__gc MUST call
  * libxl__free_all() before returning.
  */
+/*
+ * libxl types
+ *
+ * Most libxl types are defined by the libxl IDL (see
+ * libxl_types.idl). The library provides a common set of methods for
+ * initialising and freeing these types.
+ *
+ * void libxl_<type>_init(<type> *p):
+ *
+ *    Initialises the members of "p" to all defaults. These may either
+ *    be special value which indicates to the library that it should
+ *    select an appropriate default when using this field or actual
+ *    default values.
+ *
+ *    Some fields within a data type (e.g. unions) cannot be sensibly
+ *    initialised without further information. In these cases a
+ *    separate subfield initialisation function is provided (see
+ *    below).
+ *
+ *    An instance which has been initialised using this method can
+ *    always be safely passed to the dispose function (see
+ *    below). This is true even if the data type contains fields which
+ *    require a separate call to a subfield initialisation function.
+ *
+ *    This method is provided for any aggregate type which is used as
+ *    an input parameter.
+ *
+ * void libxl_<type>_init_<subfield>(<type> *p, subfield):
+ *
+ *    Initialise those parts of "p" which are not initialised by the
+ *    main init function due to the unknown value of "subfield". Sets
+ *    p->subfield as well as initialising any fields to their default
+ *    values.
+ *
+ *    p->subfield must not have been previously initialised.
+ *
+ *    This method is provided for any aggregate type which is used as
+ *    an input parameter.
+ *
+ * void libxl_<type>_dispose(instance *p):
+ *
+ *    Frees any dynamically allocated memory used by the members of
+ *    "p" but not the storage used by "p" itself (this allows for the
+ *    allocation of arrays of types and for the composition of types).
+ *
+ *    In general this method is only provided for types where memory
+ *    can be dynamically allocated as part of that type.
+ */
 #ifndef LIBXL_H
 #define LIBXL_H
 
@@ -405,8 +453,9 @@ libxl_vminfo * libxl_list_vm(libxl_ctx *
  * additional data type libxl_device_<TYPE>_getinfo which contains
  * further runtime information about the device.
  *
- * A common set of methods are available for each device type. These
- * are described below.
+ * In addition to the general methods available for libxl types (see
+ * "libxl types" above) a common set of methods are available for each
+ * device type. These are described below.
  *
  * Querying
  * --------
@@ -424,10 +473,6 @@ libxl_vminfo * libxl_list_vm(libxl_ctx *
  * Creation / Control
  * ------------------
  *
- * libxl_device_<type>_init(ctx, device):
- *
- *    Initalises device to a default configuration.
- *
  * libxl_device_<type>_add(ctx, domid, device):
  *
  *   Adds the given device to the specified domain. This can be called
diff -r 1d0bcc8cafd5 -r d50c4dc75271 tools/libxl/libxl_internal.h
--- a/tools/libxl/libxl_internal.h      Mon Feb 13 15:35:18 2012 +0000
+++ b/tools/libxl/libxl_internal.h      Mon Feb 13 15:35:18 2012 +0000
@@ -665,6 +665,19 @@ _hidden int libxl__device_destroy(libxl_
 _hidden int libxl__devices_destroy(libxl__gc *gc, uint32_t domid);
 _hidden int libxl__wait_for_backend(libxl__gc *gc, char *be_path, char *state);
 
+/*
+ * For each aggregate type which can be used as an input we provide:
+ *
+ * int libxl__<type>_setdefault(gc, <type> *p):
+ *
+ *     Idempotently sets any members of "p" which is currently set to
+ *     a special value indicating that the defaults should be used
+ *     (per libxl_<type>_init) to a specific value.
+ *
+ *     All libxl API functions are expected to have arranged for this
+ *     to be called before using any values within these structures.
+ */
+
 /* Arranges that dev will be removed from its guest.  When
  * this is done, the ao will be completed.  An error
  * return from libxl__initiate_device_remove means that the ao

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