mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-24 06:35:24 +00:00
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@very.puzzling.org>
This commit is contained in:
Michael Chapman
Michal Privoznik
parent
41d9246202
commit
030cbd6302
126
src/datatypes.c
126
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)
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user