[libvirt] [PATCH 1/8] save: document new public API

[Daniel P. Berrange]

On Thu, Jul 14, 2011 at 08:24:28AM -0600, Eric Blake wrote:
> In order to choose whether to use O_DIRECT when saving a domain image
> to a file, we need a new flag.  But virDomainSave was implemented
> before our policy of all new APIs having a flag argument.
> 
> * include/libvirt/libvirt.h.in (virDomainSaveFlags): New prototype.
> * src/libvirt.c (virDomainSaveFlags): New API.
> * src/libvirt_public.syms: Export it.
> * src/driver.h (virDrvDomainSaveFlags): New driver callback.
> ---
>  include/libvirt/libvirt.h.in |   14 ++++++
>  src/driver.h                 |    6 +++
>  src/libvirt.c                |   94 +++++++++++++++++++++++++++++++++++++++++-
>  src/libvirt_public.syms      |    5 ++
>  4 files changed, 118 insertions(+), 1 deletions(-)
> 
> diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
> index d5a7105..d9a8694 100644
> --- a/include/libvirt/libvirt.h.in
> +++ b/include/libvirt/libvirt.h.in
> @@ -659,6 +659,7 @@ typedef virDomainMemoryStatStruct *virDomainMemoryStatPtr;
>  typedef enum {
>      VIR_DUMP_CRASH   = (1 << 0), /* crash after dump */
>      VIR_DUMP_LIVE    = (1 << 1), /* live dump */
> +    VIR_DUMP_DIRECT  = (1 << 2), /* Use O_DIRECT while saving */

I wonder if we're better off calling this 'BYPASS_CACHE' or something
like since, since O_DIRECT is just an impl detail.

> +/**
> + * virDomainSaveFlagValues:
> + * Flags for use in virDomainSaveFlags and virDomainManagedSave.
> + */
> +typedef enum {
> +    VIR_DOMAIN_SAVE_DIRECT = 1 << 0,     /* Use O_DIRECT while saving */
> +} virDomainSaveFlagValues;

Same question

> +
>  int                     virDomainSave           (virDomainPtr domain,
>                                                   const char *to);
> +int                     virDomainSaveFlags      (virDomainPtr domain,
> +                                                 const char *to,
> +                                                 const char *dxml,
> +                                                 unsigned int flags);

ACK to new API design.



Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|