[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. - 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&gt; --- 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