[libvirt] [PATCH] datatypes: Fix comments

- As of commit 2ff4c137, all virGet*() functions in datatypes.c always return pointers to new objects. Objects are not cached in a per-connection hashtable. - Fix variable names in comments for all vir*Dispose() functions in datatypes.c. - Add comments for virGetStream(), virStreamDispose(), virGetDomainSnapshot(), virDomainSnapshotDispose(). Signed-off-by: Michael Chapman <mike(a)very.puzzling.org&gt; --- src/datatypes.c | 126 +++++++++++++++++++++++++++++++++----------------------- 1 file changed, 74 insertions(+), 52 deletions(-) diff --git a/src/datatypes.c b/src/datatypes.c index 20752cd..6f98aed 100644 --- a/src/datatypes.c +++ b/src/datatypes.c @@ -96,9 +96,9 @@ VIR_ONCE_GLOBAL_INIT(virDataTypes) /** * virGetConnect: * - * Allocates a new hypervisor connection structure + * Allocates a new hypervisor connection object. * - * Returns a new pointer or NULL in case of error. + * Returns a pointer to the connection object, or NULL on error. */ virConnectPtr virGetConnect(void) @@ -126,7 +126,7 @@ error: /** * virConnectDispose: - * @conn: the hypervisor connection to release + * @obj: the hypervisor connection to release * * Unconditionally release all memory associated with a connection. * The connection object must not be used once this method returns. @@ -196,12 +196,10 @@ virConnectCloseCallbackDataDispose(void *obj) * @name: pointer to the domain name * @uuid: pointer to the uuid * - * Lookup if the domain is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new domain object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the domain, or NULL in case of failure + * Returns a pointer to the domain object, or NULL on error. */ virDomainPtr virGetDomain(virConnectPtr conn, const char *name, const unsigned char *uuid) @@ -234,7 +232,7 @@ error: /** * virDomainDispose: - * @domain: the domain to release + * @obj: the domain to release * * Unconditionally release all memory associated with a domain. * The domain object must not be used once this method returns. @@ -262,12 +260,10 @@ virDomainDispose(void *obj) * @name: pointer to the network name * @uuid: pointer to the uuid * - * Lookup if the network is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new network object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the network, or NULL in case of failure + * Returns a pointer to the network object, or NULL on error. */ virNetworkPtr virGetNetwork(virConnectPtr conn, const char *name, const unsigned char *uuid) @@ -299,7 +295,7 @@ error: /** * virNetworkDispose: - * @network: the network to release + * @obj: the network to release * * Unconditionally release all memory associated with a network. * The network object must not be used once this method returns. @@ -327,13 +323,10 @@ virNetworkDispose(void *obj) * @name: pointer to the interface name * @mac: pointer to the mac * - * Lookup if the interface is already registered for that connection, - * if yes return a new pointer to it (possibly updating the MAC - * address), if no allocate a new structure, and register it in the - * table. In any case a corresponding call to virObjectUnref() is - * needed to not leak data. + * Allocates a new interface object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the interface, or NULL in case of failure + * Returns a pointer to the interface object, or NULL on error. */ virInterfacePtr virGetInterface(virConnectPtr conn, const char *name, const char *mac) @@ -368,7 +361,7 @@ error: /** * virInterfaceDispose: - * @interface: the interface to release + * @obj: the interface to release * * Unconditionally release all memory associated with an interface. * The interface object must not be used once this method returns. @@ -396,12 +389,10 @@ virInterfaceDispose(void *obj) * @privateData: pointer to driver specific private data * @freeFunc: private data cleanup function pointer specfic to driver * - * Lookup if the storage pool is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new storage pool object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the storage pool, or NULL in case of failure + * Returns a pointer to the storage pool object, or NULL on error. */ virStoragePoolPtr virGetStoragePool(virConnectPtr conn, const char *name, @@ -440,7 +431,7 @@ error: /** * virStoragePoolDispose: - * @pool: the pool to release + * @obj: the storage pool to release * * Unconditionally release all memory associated with a pool. * The pool object must not be used once this method returns. @@ -475,12 +466,10 @@ virStoragePoolDispose(void *obj) * @privateData: pointer to driver specific private data * @freeFunc: private data cleanup function pointer specfic to driver * - * Lookup if the storage vol is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new storage volume object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the storage vol, or NULL in case of failure + * Returns a pointer to the storage volume object, or NULL on error. */ virStorageVolPtr virGetStorageVol(virConnectPtr conn, const char *pool, const char *name, @@ -520,7 +509,7 @@ error: /** * virStorageVolDispose: - * @vol: the vol to release + * @obj: the storage volume to release * * Unconditionally release all memory associated with a volume. * The volume object must not be used once this method returns. @@ -550,12 +539,10 @@ virStorageVolDispose(void *obj) * @conn: the hypervisor connection * @name: device name (unique on node) * - * Lookup if the device is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new node device object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the node device, or NULL in case of failure + * Returns a pointer to the node device object, or NULL on error. */ virNodeDevicePtr virGetNodeDevice(virConnectPtr conn, const char *name) @@ -585,7 +572,7 @@ error: /** * virNodeDeviceDispose: - * @dev: the dev to release + * @obj: the node device to release * * Unconditionally release all memory associated with a device. * The device object must not be used once this method returns. @@ -611,12 +598,10 @@ virNodeDeviceDispose(void *obj) * @conn: the hypervisor connection * @uuid: secret UUID * - * Lookup if the secret is already registered for that connection, if so return - * a pointer to it, otherwise allocate a new structure, and register it in the - * table. In any case a corresponding call to virObjectUnref() is needed to not - * leak data. + * Allocates a new secret object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the secret, or NULL in case of failure + * Returns a pointer to the secret object, or NULL on error. */ virSecretPtr virGetSecret(virConnectPtr conn, const unsigned char *uuid, @@ -650,7 +635,7 @@ error: /** * virSecretDispose: - * @secret: the secret to release + * @obj: the secret to release * * Unconditionally release all memory associated with a secret. * The secret object must not be used once this method returns. @@ -672,6 +657,15 @@ virSecretDispose(void *obj) } +/** + * virGetStream: + * @conn: the hypervisor connection + * + * Allocates a new stream object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. + * + * Returns a pointer to the stream object, or NULL on error. + */ virStreamPtr virGetStream(virConnectPtr conn) { @@ -688,6 +682,16 @@ virGetStream(virConnectPtr conn) return ret; } +/** + * virStreamDispose: + * @obj: the stream to release + * + * Unconditionally release all memory associated with a stream. + * The stream object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ static void virStreamDispose(void *obj) { @@ -704,12 +708,10 @@ virStreamDispose(void *obj) * @name: pointer to the network filter pool name * @uuid: pointer to the uuid * - * Lookup if the network filter is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new network filter object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the network, or NULL in case of failure + * Returns a pointer to the network filter object, or NULL on error. */ virNWFilterPtr virGetNWFilter(virConnectPtr conn, const char *name, @@ -744,7 +746,7 @@ error: /** * virNWFilterDispose: - * @nwfilter: the nwfilter to release + * @obj: the network filter to release * * Unconditionally release all memory associated with a nwfilter. * The nwfilter object must not be used once this method returns. @@ -766,6 +768,16 @@ virNWFilterDispose(void *obj) } +/** + * virGetDomainSnapshot: + * @domain: the domain to snapshot + * @name: pointer to the domain snapshot name + * + * Allocates a new domain snapshot object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. + * + * Returns a pointer to the domain snapshot object, or NULL on error. + */ virDomainSnapshotPtr virGetDomainSnapshot(virDomainPtr domain, const char *name) { @@ -792,6 +804,16 @@ error: } +/** + * virDomainSnapshotDispose: + * @obj: the domain snapshot to release + * + * Unconditionally release all memory associated with a snapshot. + * The snapshot object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ static void virDomainSnapshotDispose(void *obj) { -- 1.8.5.3