[libvirt] [PATCH 1/2] include: declare typed parameter handling earlier
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read. * include/libvirt/libvirt.h.in: Move virTypedParameter earlier. --- include/libvirt/libvirt.h.in | 174 ++++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 86 deletions(-) diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in index 52555f8..7d6a064 100644 --- a/include/libvirt/libvirt.h.in +++ b/include/libvirt/libvirt.h.in @@ -432,6 +432,94 @@ typedef struct _virSecurityModel { */ typedef virSecurityModel *virSecurityModelPtr; +/* Common data types shared among interfaces with name/type/value lists. */ + +/** + * virTypedParameterType: + * + * Express the type of a virTypedParameter + */ +typedef enum { + VIR_TYPED_PARAM_INT = 1, /* integer case */ + VIR_TYPED_PARAM_UINT = 2, /* unsigned integer case */ + VIR_TYPED_PARAM_LLONG = 3, /* long long case */ + VIR_TYPED_PARAM_ULLONG = 4, /* unsigned long long case */ + VIR_TYPED_PARAM_DOUBLE = 5, /* double case */ + VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case */ + VIR_TYPED_PARAM_STRING = 7, /* string case */ + +#ifdef VIR_ENUM_SENTINELS + VIR_TYPED_PARAM_LAST +#endif +} virTypedParameterType; + +/** + * virTypedParameterFlags: + * + * Flags related to libvirt APIs that use virTypedParameter. + * + * These enums should not conflict with those of virDomainModificationImpact. + */ +typedef enum { + /* 1 << 0 is reserved for virDomainModificationImpact */ + /* 1 << 1 is reserved for virDomainModificationImpact */ + + /* Older servers lacked the ability to handle string typed + * parameters. Attempts to set a string parameter with an older + * server will fail at the client, but attempts to retrieve + * parameters must not return strings from a new server to an + * older client, so this flag exists to identify newer clients to + * newer servers. This flag is automatically set when needed, so + * the user does not have to worry about it; however, manually + * setting the flag can be used to reject servers that cannot + * return typed strings, even if no strings would be returned. + */ + VIR_TYPED_PARAM_STRING_OKAY = 1 << 2, + +} virTypedParameterFlags; + +/** + * VIR_TYPED_PARAM_FIELD_LENGTH: + * + * Macro providing the field length of virTypedParameter name + */ +#define VIR_TYPED_PARAM_FIELD_LENGTH 80 + +/** + * virTypedParameter: + * + * A named parameter, including a type and value. + * + * The types virSchedParameter, virBlkioParameter, and + * virMemoryParameter are aliases of this type, for use when + * targetting libvirt earlier than 0.9.2. + */ +typedef struct _virTypedParameter virTypedParameter; + +struct _virTypedParameter { + char field[VIR_TYPED_PARAM_FIELD_LENGTH]; /* parameter name */ + int type; /* parameter type, virTypedParameterType */ + union { + int i; /* type is INT */ + unsigned int ui; /* type is UINT */ + long long int l; /* type is LLONG */ + unsigned long long int ul; /* type is ULLONG */ + double d; /* type is DOUBLE */ + char b; /* type is BOOLEAN */ + char *s; /* type is STRING, may not be NULL */ + } value; /* parameter value */ +}; + +/** + * virTypedParameterPtr: + * + * a pointer to a virTypedParameter structure. + */ +typedef virTypedParameter *virTypedParameterPtr; + + +/* data types relate to virNodePtr */ + /** * virNodeInfoPtr: * @@ -587,92 +675,6 @@ struct _virNodeMemoryStats { unsigned long long value; }; -/* Common data types shared among interfaces with name/type/value lists. */ - -/** - * virTypedParameterType: - * - * Express the type of a virTypedParameter - */ -typedef enum { - VIR_TYPED_PARAM_INT = 1, /* integer case */ - VIR_TYPED_PARAM_UINT = 2, /* unsigned integer case */ - VIR_TYPED_PARAM_LLONG = 3, /* long long case */ - VIR_TYPED_PARAM_ULLONG = 4, /* unsigned long long case */ - VIR_TYPED_PARAM_DOUBLE = 5, /* double case */ - VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case */ - VIR_TYPED_PARAM_STRING = 7, /* string case */ - -#ifdef VIR_ENUM_SENTINELS - VIR_TYPED_PARAM_LAST -#endif -} virTypedParameterType; - -/** - * virTypedParameterFlags: - * - * Flags related to libvirt APIs that use virTypedParameter. - * - * These enums should not conflict with those of virDomainModificationImpact. - */ -typedef enum { - /* 1 << 0 is reserved for virDomainModificationImpact */ - /* 1 << 1 is reserved for virDomainModificationImpact */ - - /* Older servers lacked the ability to handle string typed - * parameters. Attempts to set a string parameter with an older - * server will fail at the client, but attempts to retrieve - * parameters must not return strings from a new server to an - * older client, so this flag exists to identify newer clients to - * newer servers. This flag is automatically set when needed, so - * the user does not have to worry about it; however, manually - * setting the flag can be used to reject servers that cannot - * return typed strings, even if no strings would be returned. - */ - VIR_TYPED_PARAM_STRING_OKAY = 1 << 2, - -} virTypedParameterFlags; - -/** - * VIR_TYPED_PARAM_FIELD_LENGTH: - * - * Macro providing the field length of virTypedParameter name - */ -#define VIR_TYPED_PARAM_FIELD_LENGTH 80 - -/** - * virTypedParameter: - * - * A named parameter, including a type and value. - * - * The types virSchedParameter, virBlkioParameter, and - * virMemoryParameter are aliases of this type, for use when - * targetting libvirt earlier than 0.9.2. - */ -typedef struct _virTypedParameter virTypedParameter; - -struct _virTypedParameter { - char field[VIR_TYPED_PARAM_FIELD_LENGTH]; /* parameter name */ - int type; /* parameter type, virTypedParameterType */ - union { - int i; /* type is INT */ - unsigned int ui; /* type is UINT */ - long long int l; /* type is LLONG */ - unsigned long long int ul; /* type is ULLONG */ - double d; /* type is DOUBLE */ - char b; /* type is BOOLEAN */ - char *s; /* type is STRING, may not be NULL */ - } value; /* parameter value */ -}; - -/** - * virTypedParameterPtr: - * - * a pointer to a virTypedParameter structure. - */ -typedef virTypedParameter *virTypedParameterPtr; - - /* Management of scheduler parameters */ /** -- 1.7.11.7
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read. * include/libvirt/libvirt.h.in: Move virNodeGetMemoryParameters and friends earlier, add a note to prevent relapse. --- include/libvirt/libvirt.h.in | 151 ++++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 74 deletions(-) diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in index 7d6a064..52357d6 100644 --- a/include/libvirt/libvirt.h.in +++ b/include/libvirt/libvirt.h.in @@ -675,6 +675,81 @@ struct _virNodeMemoryStats { unsigned long long value; }; +/* + * VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN: + * + * Macro for typed parameter that represents how many present pages + * to scan before the shared memory service goes to sleep. + */ +# define VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN "shm_pages_to_scan" + +/* + * VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS: + * + * Macro for typed parameter that represents how many milliseconds + * the shared memory service should sleep before next scan. + */ +# define VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS "shm_sleep_millisecs" + +/* + * VIR_NODE_MEMORY_SHARED_PAGES_SHARED: + * + * Macro for typed parameter that represents how many the shared + * memory pages are being used. + */ +# define VIR_NODE_MEMORY_SHARED_PAGES_SHARED "shm_pages_shared" + +/* + * VIR_NODE_MEMORY_SHARED_PAGES_SHARING: + * + * Macro for typed parameter that represents how many sites are + * sharing the pages i.e. how much saved. + */ +# define VIR_NODE_MEMORY_SHARED_PAGES_SHARING "shm_pages_sharing" + +/* VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED: + * + * Macro for typed parameter that represents how many pages unique + * but repeatedly checked for merging. + */ +# define VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED "shm_pages_unshared" + +/* VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE: + * + * Macro for typed parameter that represents how many pages changing + * too fast to be placed in a tree. + */ +# define VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE "shm_pages_volatile" + +/* VIR_NODE_MEMORY_SHARED_FULL_SCAN: + * + * Macro for typed parameter that represents how many times all + * mergeable areas have been scanned. + */ +# define VIR_NODE_MEMORY_SHARED_FULL_SCANS "shm_full_scans" + +/* VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES: + * + * Macro for typed parameter that represents whether pages from + * different NUMA nodes can be merged. The parameter has type int, + * when its value is 0, only pages which physically reside in the + * memory area of same NUMA node are merged; When its value is 1, + * pages from all nodes can be merged. Other values are reserved + * for future use. + */ +# define VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES "shm_merge_across_nodes" + + +int virNodeGetMemoryParameters(virConnectPtr conn, + virTypedParameterPtr params, + int *nparams, + unsigned int flags); + +int virNodeSetMemoryParameters(virConnectPtr conn, + virTypedParameterPtr params, + int nparams, + unsigned int flags); + /* Management of scheduler parameters */ /** @@ -4468,80 +4543,8 @@ typedef struct _virTypedParameter virMemoryParameter; */ typedef virMemoryParameter *virMemoryParameterPtr; -/* - * VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN: - * - * Macro for typed parameter that represents how many present pages - * to scan before the shared memory service goes to sleep. - */ -# define VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN "shm_pages_to_scan" - -/* - * VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS: - * - * Macro for typed parameter that represents how many milliseconds - * the shared memory service should sleep before next scan. - */ -# define VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS "shm_sleep_millisecs" - -/* - * VIR_NODE_MEMORY_SHARED_PAGES_SHARED: - * - * Macro for typed parameter that represents how many the shared - * memory pages are being used. - */ -# define VIR_NODE_MEMORY_SHARED_PAGES_SHARED "shm_pages_shared" - -/* - * VIR_NODE_MEMORY_SHARED_PAGES_SHARING: - * - * Macro for typed parameter that represents how many sites are - * sharing the pages i.e. how much saved. - */ -# define VIR_NODE_MEMORY_SHARED_PAGES_SHARING "shm_pages_sharing" - -/* VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED: - * - * Macro for typed parameter that represents how many pages unique - * but repeatedly checked for merging. - */ -# define VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED "shm_pages_unshared" - -/* VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE: - * - * Macro for typed parameter that represents how many pages changing - * too fast to be placed in a tree. - */ -# define VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE "shm_pages_volatile" - -/* VIR_NODE_MEMORY_SHARED_FULL_SCAN: - * - * Macro for typed parameter that represents how many times all - * mergeable areas have been scanned. - */ -# define VIR_NODE_MEMORY_SHARED_FULL_SCANS "shm_full_scans" - -/* VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES: - * - * Macro for typed parameter that represents whether pages from - * different NUMA nodes can be merged. The parameter has type int, - * when its value is 0, only pages which physically reside in the - * memory area of same NUMA node are merged; When its value is 1, - * pages from all nodes can be merged. Other values are reserved - * for future use. - */ -# define VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES "shm_merge_across_nodes" - - -int virNodeGetMemoryParameters(virConnectPtr conn, - virTypedParameterPtr params, - int *nparams, - unsigned int flags); - -int virNodeSetMemoryParameters(virConnectPtr conn, - virTypedParameterPtr params, - int nparams, - unsigned int flags); +/* Add new interfaces to the appropriate sections earlier in this + * file; the end of the file is reserved for deprecated names. */ #ifdef __cplusplus } -- 1.7.11.7
On 10/23/2012 02:01 PM, Eric Blake wrote:
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read.
* include/libvirt/libvirt.h.in: Move virNodeGetMemoryParameters and friends earlier, add a note to prevent relapse.
And again with the code movement. ACK.
On 10/23/2012 12:11 PM, Laine Stump wrote:
On 10/23/2012 02:01 PM, Eric Blake wrote:
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read.
* include/libvirt/libvirt.h.in: Move virNodeGetMemoryParameters and friends earlier, add a note to prevent relapse.
And again with the code movement. ACK.
Thanks; pushed. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On 10/23/2012 02:01 PM, Eric Blake wrote:
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read.
* include/libvirt/libvirt.h.in: Move virTypedParameter earlier.
Pure code movement. ACK.
On Tue, Oct 23, 2012 at 12:01:02PM -0600, Eric Blake wrote:
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read.
* include/libvirt/libvirt.h.in: Move virTypedParameter earlier. --- include/libvirt/libvirt.h.in | 174 ++++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 86 deletions(-)
I have to say I would dearly love to split up our header file into a number of pieces, since it is really a huge mess as it is. I'd like to have libvirt/virerror.h libvirt/virmisc.h libvirt/virconnect.h libvirt/virdomain.h libvirt/virnetwork.h libvirt/virnodedev.h libvirt/virinterface.h libvirt/..etc... In keeping with the way GTK works, applications would *not* include the individual header files directly - they'd simply continue to use libvirt.h as now, which would in turn #include all the individual pieces. 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 :|
On 10/24/2012 03:20 AM, Daniel P. Berrange wrote:
On Tue, Oct 23, 2012 at 12:01:02PM -0600, Eric Blake wrote:
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read.
* include/libvirt/libvirt.h.in: Move virTypedParameter earlier. --- include/libvirt/libvirt.h.in | 174 ++++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 86 deletions(-)
I have to say I would dearly love to split up our header file into a number of pieces, since it is really a huge mess as it is. I'd like to have
libvirt/virerror.h libvirt/virmisc.h libvirt/virconnect.h libvirt/virdomain.h libvirt/virnetwork.h libvirt/virnodedev.h libvirt/virinterface.h libvirt/..etc...
Agreed, and this is not the first time this has come up. However, the last time I attempted this, I ran into walls trying to figure out how to make the documentation generation work across multiple headers, and it wasn't high enough on my priorities to resolve at that time. Also, it sounds invasive enough to save until after 1.0.0 is released.
In keeping with the way GTK works, applications would *not* include the individual header files directly - they'd simply continue to use libvirt.h as now, which would in turn #include all the individual pieces.
Daniel
-- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On Wed, Oct 24, 2012 at 08:30:02AM -0600, Eric Blake wrote:
On 10/24/2012 03:20 AM, Daniel P. Berrange wrote:
On Tue, Oct 23, 2012 at 12:01:02PM -0600, Eric Blake wrote:
Commit 12ad7435 added new functions (virNodeGetMemoryParameters, virNodeSetMemoryParameters) into the section of the file reserved for deprecated names. Fix this by moving things earlier; split into two patches to make git diff easier to read.
* include/libvirt/libvirt.h.in: Move virTypedParameter earlier. --- include/libvirt/libvirt.h.in | 174 ++++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 86 deletions(-)
I have to say I would dearly love to split up our header file into a number of pieces, since it is really a huge mess as it is. I'd like to have
libvirt/virerror.h libvirt/virmisc.h libvirt/virconnect.h libvirt/virdomain.h libvirt/virnetwork.h libvirt/virnodedev.h libvirt/virinterface.h libvirt/..etc...
Agreed, and this is not the first time this has come up. However, the last time I attempted this, I ran into walls trying to figure out how to make the documentation generation work across multiple headers, and it wasn't high enough on my priorities to resolve at that time. Also, it sounds invasive enough to save until after 1.0.0 is released.
Oh right, forgot about the docs generator pain. Of course it can wait till after 1.0.0 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 :|
On Wed, Oct 24, 2012 at 03:31:24PM +0100, Daniel P. Berrange wrote:
On Wed, Oct 24, 2012 at 08:30:02AM -0600, Eric Blake wrote:
On 10/24/2012 03:20 AM, Daniel P. Berrange wrote:
Agreed, and this is not the first time this has come up. However, the last time I attempted this, I ran into walls trying to figure out how to make the documentation generation work across multiple headers, and it wasn't high enough on my priorities to resolve at that time. Also, it sounds invasive enough to save until after 1.0.0 is released.
Oh right, forgot about the docs generator pain. Of course it can wait till after 1.0.0
"fixing" the generator should not be too hard, libxml2 also uses split headers and the generator handle it, I guess it should be a few lines of cut and paste or copy. The libxml2 version parses all .h found by glob unless listed in self.excludes, and the libvirt version evolved to restrict to the ones found in the self.includes Two options: + extend the include to the new set of files possibly by doing a glob in the directory containing libvirt.h + switch to an exclude mechanism, but it may become painful to maintain Related code is docs/apibuild.py rebuild() and docBuilder::scan() Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
participants (4)
-
Daniel P. Berrange -
Daniel Veillard -
Eric Blake -
Laine Stump