[libvirt] [PATCH] datatypes: Fix comments
Michael Chapman
mike at very.puzzling.org
Tue Mar 11 04:04:59 UTC 2014
- 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 at very.puzzling.org>
---
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
More information about the libvir-list
mailing list