[PATCH] datatypes: Fix comments

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



- 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@xxxxxxxxxxxxxxxxx>
---
 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

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]