- 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.
- As of commit 46ec5f85, the conn.lock mutex does not need to be held
when calling any vir*Dispose() function in datatypes.c (via
virObjectUnref()).
- Add comments for virGetStream(), virStreamDispose(),
virGetDomainSnapshot(), virDomainSnapshotDispose().
Signed-off-by: Michael Chapman <mike(a)very.puzzling.org>
---
src/datatypes.c | 174 ++++++++++++++++++++++++++++++++------------------------
1 file changed, 99 insertions(+), 75 deletions(-)
diff --git a/src/datatypes.c b/src/datatypes.c
index 73f17e7..aafa54b 100644
--- a/src/datatypes.c
+++ b/src/datatypes.c
@@ -96,9 +96,8 @@ VIR_ONCE_GLOBAL_INIT(virDataTypes)
/**
* virGetConnect:
*
- * Allocates a new hypervisor connection structure
- *
- * Returns a new pointer or NULL in case of error.
+ * Allocates and returns a pointer to a new hypervisor connection object.
+ * Returns NULL on error.
*/
virConnectPtr
virGetConnect(void)
@@ -129,9 +128,7 @@ error:
* @conn: the hypervisor connection to release
*
* Unconditionally release all memory associated with a connection.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The connection obj must not
- * be used once this method returns.
+ * The connection object must not be used once this method returns.
*/
static void
virConnectDispose(void *obj)
@@ -198,12 +195,12 @@ 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 and returns a pointer to a new domain object.
+ * Returns NULL on error.
*
- * Returns a pointer to the domain, or NULL in case of failure
+ * The domain object holds a reference to the hypervisor connection.
+ * When the domain object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virDomainPtr
virGetDomain(virConnectPtr conn, const char *name, const unsigned char *uuid)
@@ -239,9 +236,7 @@ error:
* @domain: the domain to release
*
* Unconditionally release all memory associated with a domain.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The domain obj must not
- * be used once this method returns.
+ * The domain 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.
@@ -266,12 +261,12 @@ 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 and returns a pointer to a new network object.
+ * Returns NULL on error.
*
- * Returns a pointer to the network, or NULL in case of failure
+ * The network object holds a reference to the hypervisor connection.
+ * When the network object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virNetworkPtr
virGetNetwork(virConnectPtr conn, const char *name, const unsigned char *uuid)
@@ -306,9 +301,7 @@ error:
* @network: the network to release
*
* Unconditionally release all memory associated with a network.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The network obj must not
- * be used once this method returns.
+ * The network 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.
@@ -333,13 +326,12 @@ 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 and returns a pointer to a new interface object.
+ * Returns NULL on error.
*
- * Returns a pointer to the interface, or NULL in case of failure
+ * The interface object holds a reference to the hypervisor connection.
+ * When the interface object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virInterfacePtr
virGetInterface(virConnectPtr conn, const char *name, const char *mac)
@@ -377,9 +369,7 @@ error:
* @interface: the interface to release
*
* Unconditionally release all memory associated with an interface.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The interface obj must not
- * be used once this method returns.
+ * The interface 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.
@@ -404,12 +394,12 @@ 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 and returns a pointer to a new storage pool object.
+ * Returns NULL on error.
*
- * Returns a pointer to the storage pool, or NULL in case of failure
+ * The pool object holds a reference to the hypervisor connection.
+ * When the pool object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virStoragePoolPtr
virGetStoragePool(virConnectPtr conn, const char *name,
@@ -451,9 +441,7 @@ error:
* @pool: the pool to release
*
* Unconditionally release all memory associated with a pool.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The pool obj must not
- * be used once this method returns.
+ * The pool 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.
@@ -485,12 +473,12 @@ 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 and returns a pointer to a new storage volume object.
+ * Returns NULL on error.
*
- * Returns a pointer to the storage vol, or NULL in case of failure
+ * The volume object holds a reference to the hypervisor connection.
+ * When the volume object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virStorageVolPtr
virGetStorageVol(virConnectPtr conn, const char *pool, const char *name,
@@ -532,10 +520,8 @@ error:
* virStorageVolDispose:
* @vol: the vol to release
*
- * Unconditionally release all memory associated with a vol.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The vol obj must not
- * be used once this method returns.
+ * Unconditionally release all memory associated with a volume.
+ * The volume 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.
@@ -562,12 +548,12 @@ 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 and returns a pointer to a new node device object.
+ * Returns NULL on error.
*
- * Returns a pointer to the node device, or NULL in case of failure
+ * The device object holds a reference to the hypervisor connection.
+ * When the device object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virNodeDevicePtr
virGetNodeDevice(virConnectPtr conn, const char *name)
@@ -599,10 +585,8 @@ error:
* virNodeDeviceDispose:
* @dev: the dev to release
*
- * Unconditionally release all memory associated with a dev.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The dev obj must not
- * be used once this method returns.
+ * Unconditionally release all memory associated with a device.
+ * The device 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.
@@ -625,12 +609,12 @@ 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 and returns a pointer to a new secret object.
+ * Returns NULL on error.
*
- * Returns a pointer to the secret, or NULL in case of failure
+ * The secret object holds a reference to the hypervisor connection.
+ * When the secret object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virSecretPtr
virGetSecret(virConnectPtr conn, const unsigned char *uuid,
@@ -666,12 +650,11 @@ error:
* virSecretDispose:
* @secret: the secret to release
*
- * Unconditionally release all memory associated with a secret. The conn.lock
- * mutex must be held prior to calling this, and will be released prior to this
- * returning. The secret obj must not be used once this method returns.
+ * Unconditionally release all memory associated with a secret.
+ * The secret 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.
+ * It will also unreference the associated connection object,
+ * which may also be released if its ref count hits zero.
*/
static void
virSecretDispose(void *obj)
@@ -687,6 +670,17 @@ virSecretDispose(void *obj)
}
+/**
+ * virGetStream:
+ * @conn: the hypervisor connection
+ *
+ * Allocates and returns a pointer to a new stream object.
+ * Returns NULL on error.
+ *
+ * The secret object holds a reference to the hypervisor connection.
+ * When the secret object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
+ */
virStreamPtr
virGetStream(virConnectPtr conn)
{
@@ -703,6 +697,16 @@ virGetStream(virConnectPtr conn)
return ret;
}
+/**
+ * virStreamDispose:
+ * @stream: 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)
{
@@ -719,12 +723,12 @@ 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 and returns a pointer to a new nwfilter object.
+ * Returns NULL on error.
*
- * Returns a pointer to the network, or NULL in case of failure
+ * The nwfilter object holds a reference to the hypervisor connection.
+ * When the nwfilter object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
*/
virNWFilterPtr
virGetNWFilter(virConnectPtr conn, const char *name,
@@ -762,9 +766,7 @@ error:
* @nwfilter: the nwfilter to release
*
* Unconditionally release all memory associated with a nwfilter.
- * The conn.lock mutex must be held prior to calling this, and will
- * be released prior to this returning. The nwfilter obj must not
- * be used once this method returns.
+ * The nwfilter 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.
@@ -783,6 +785,18 @@ virNWFilterDispose(void *obj)
}
+/**
+ * virGetDomainSnapshot:
+ * @conn: the hypervisor connection
+ * @name: pointer to the domain snapshot name
+ *
+ * Allocates and returns a pointer to a new domain snapshot object.
+ * Returns NULL on error.
+ *
+ * The snapshot object holds a reference to the hypervisor connection.
+ * When the snapshot object is no longer needed, virObjectUnref() must be
+ * called in order to not leak data.
+ */
virDomainSnapshotPtr
virGetDomainSnapshot(virDomainPtr domain, const char *name)
{
@@ -809,6 +823,16 @@ error:
}
+/**
+ * virDomainSnapshotDispose:
+ * @snapshot: the 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
