Add public APIs for ref counting on public objects

diff --git a/ChangeLog b/ChangeLog
index e166eaa2a6c5de8bc31cd2c3ca06dc7f6de63128..0ed5708cca7412a38adc485e63ef5796a38421b1 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+Tue Jan 20 12:08:53 GMT 2009 Daniel P. Berrange <berrange@redhat.com>
+
+       * include/libvirt/libvirt.h, include/libvirt/libvirt.h.in,
+       src/libvirt.c, src/libvirt_public.syms: Add new ref counting
+       APIs for public objects: virConnectRef, virDomainRef,
+        virNetworkRef, virStoragePoolRef, virStorageVolRef,
+        virNodeDeviceRef
+
 Tue Jan 20 12:03:53 GMT 2009 Daniel P. Berrange <berrange@redhat.com>
 
        * tests/cpuset, tests/read-bufsiz, tests/start, tests/undefine,

diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h
index 97b448993b83a7600f6ef120107de8a42560fc47..29115da5fd5cd0055675983eccedba5f4030c541 100644 (file)
--- a/include/libvirt/libvirt.h
+++ b/include/libvirt/libvirt.h
@@ -396,6 +396,7 @@ virConnectPtr           virConnectOpenReadOnly  (const char *name);
 virConnectPtr           virConnectOpenAuth      (const char *name,
                                                  virConnectAuthPtr auth,
                                                  int flags);
+int                     virConnectRef           (virConnectPtr conn);
 int                     virConnectClose         (virConnectPtr conn);
 const char *            virConnectGetType       (virConnectPtr conn);
 int                     virConnectGetVersion    (virConnectPtr conn,
@@ -453,6 +454,7 @@ int                     virDomainShutdown       (virDomainPtr domain);
 int                     virDomainReboot         (virDomainPtr domain,
                                                  unsigned int flags);
 int                     virDomainDestroy        (virDomainPtr domain);
+int                     virDomainRef            (virDomainPtr domain);
 int                     virDomainFree           (virDomainPtr domain);
 
 /*
@@ -765,6 +767,7 @@ int                     virNetworkCreate        (virNetworkPtr network);
  * Network destroy/free
  */
 int                     virNetworkDestroy       (virNetworkPtr network);
+int                     virNetworkRef           (virNetworkPtr network);
 int                     virNetworkFree          (virNetworkPtr network);
 
 /*
@@ -925,6 +928,7 @@ int                     virStoragePoolCreate            (virStoragePoolPtr pool,
 int                     virStoragePoolDestroy           (virStoragePoolPtr pool);
 int                     virStoragePoolDelete            (virStoragePoolPtr pool,
                                                          unsigned int flags);
+int                     virStoragePoolRef               (virStoragePoolPtr pool);
 int                     virStoragePoolFree              (virStoragePoolPtr pool);
 int                     virStoragePoolRefresh           (virStoragePoolPtr pool,
                                                          unsigned int flags);
@@ -978,6 +982,7 @@ virStorageVolPtr        virStorageVolCreateXML          (virStoragePoolPtr pool,
                                                          unsigned int flags);
 int                     virStorageVolDelete             (virStorageVolPtr vol,
                                                          unsigned int flags);
+int                     virStorageVolRef                (virStorageVolPtr vol);
 int                     virStorageVolFree               (virStorageVolPtr vol);
 
 int                     virStorageVolGetInfo            (virStorageVolPtr vol,
@@ -1045,6 +1050,7 @@ int                     virNodeDeviceListCaps    (virNodeDevicePtr dev,
 char *                  virNodeDeviceGetXMLDesc (virNodeDevicePtr dev,
                                                  unsigned int flags);
 
+int                     virNodeDeviceRef        (virNodeDevicePtr dev);
 int                     virNodeDeviceFree       (virNodeDevicePtr dev);
 
 /*

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index fc322e6b0f0a94690112c62970af50150595d6a2..af97bfd35ee0012e6b675f7ec3fff66303ac3e66 100644 (file)
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -396,6 +396,7 @@ virConnectPtr           virConnectOpenReadOnly  (const char *name);
 virConnectPtr           virConnectOpenAuth      (const char *name,
                                                  virConnectAuthPtr auth,
                                                  int flags);
+int                     virConnectRef           (virConnectPtr conn);
 int                     virConnectClose         (virConnectPtr conn);
 const char *            virConnectGetType       (virConnectPtr conn);
 int                     virConnectGetVersion    (virConnectPtr conn,
@@ -453,6 +454,7 @@ int                     virDomainShutdown       (virDomainPtr domain);
 int                     virDomainReboot         (virDomainPtr domain,
                                                  unsigned int flags);
 int                     virDomainDestroy        (virDomainPtr domain);
+int                     virDomainRef            (virDomainPtr domain);
 int                     virDomainFree           (virDomainPtr domain);
 
 /*
@@ -765,6 +767,7 @@ int                     virNetworkCreate        (virNetworkPtr network);
  * Network destroy/free
  */
 int                     virNetworkDestroy       (virNetworkPtr network);
+int                     virNetworkRef           (virNetworkPtr network);
 int                     virNetworkFree          (virNetworkPtr network);
 
 /*
@@ -925,6 +928,7 @@ int                     virStoragePoolCreate            (virStoragePoolPtr pool,
 int                     virStoragePoolDestroy           (virStoragePoolPtr pool);
 int                     virStoragePoolDelete            (virStoragePoolPtr pool,
                                                          unsigned int flags);
+int                     virStoragePoolRef               (virStoragePoolPtr pool);
 int                     virStoragePoolFree              (virStoragePoolPtr pool);
 int                     virStoragePoolRefresh           (virStoragePoolPtr pool,
                                                          unsigned int flags);
@@ -978,6 +982,7 @@ virStorageVolPtr        virStorageVolCreateXML          (virStoragePoolPtr pool,
                                                          unsigned int flags);
 int                     virStorageVolDelete             (virStorageVolPtr vol,
                                                          unsigned int flags);
+int                     virStorageVolRef                (virStorageVolPtr vol);
 int                     virStorageVolFree               (virStorageVolPtr vol);
 
 int                     virStorageVolGetInfo            (virStorageVolPtr vol,
@@ -1045,6 +1050,7 @@ int                     virNodeDeviceListCaps    (virNodeDevicePtr dev,
 char *                  virNodeDeviceGetXMLDesc (virNodeDevicePtr dev,
                                                  unsigned int flags);
 
+int                     virNodeDeviceRef        (virNodeDevicePtr dev);
 int                     virNodeDeviceFree       (virNodeDevicePtr dev);
 
 /*

diff --git a/src/libvirt.c b/src/libvirt.c
index ae1a04e3cc0267f2e6195ac8a12522e410b03095..2bb46e4ba2a2ac6f3ec68d58b281e44ae8cd6c5e 100644 (file)
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -1119,6 +1119,35 @@ virConnectClose(virConnectPtr conn)
     return (0);
 }
 
+/**
+ * virConnectRef:
+ * @conn: the connection to hold a reference on
+ *
+ * Increment the reference count on the connection. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virConnectClose to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection remain open until all threads have finished using
+ * it. ie, each new thread using a connection would increment
+ * the reference count.
+ */
+int
+virConnectRef(virConnectPtr conn)
+{
+    if ((!VIR_IS_CONNECT(conn))) {
+        virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return(-1);
+    }
+    virMutexLock(&conn->lock);
+    DEBUG("conn=%p refs=%d", conn, conn->refs);
+    conn->refs++;
+    virMutexUnlock(&conn->lock);
+    return 0;
+}
+
 /*
  * Not for public use.  This function is part of the internal
  * implementation of driver features in the remote case.
@@ -1776,6 +1805,36 @@ virDomainFree(virDomainPtr domain)
     return(0);
 }
 
+/**
+ * virDomainRef:
+ * @conn: the domain to hold a reference on
+ *
+ * Increment the reference count on the domain. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virDomainFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection remain open until all threads have finished using
+ * it. ie, each new thread using a domain would increment
+ * the reference count.
+ */
+int
+virDomainRef(virDomainPtr domain)
+{
+    if ((!VIR_IS_CONNECTED_DOMAIN(domain))) {
+        virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return(-1);
+    }
+    virMutexLock(&domain->conn->lock);
+    DEBUG("domain=%p refs=%d", domain, domain->refs);
+    domain->refs++;
+    virMutexUnlock(&domain->conn->lock);
+    return 0;
+}
+
+
 /**
  * virDomainSuspend:
  * @domain: a domain object
@@ -4813,6 +4872,35 @@ virNetworkFree(virNetworkPtr network)
     return(0);
 }
 
+/**
+ * virNetworkRef:
+ * @conn: the network to hold a reference on
+ *
+ * Increment the reference count on the network. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virNetworkFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection remain open until all threads have finished using
+ * it. ie, each new thread using a network would increment
+ * the reference count.
+ */
+int
+virNetworkRef(virNetworkPtr network)
+{
+    if ((!VIR_IS_CONNECTED_NETWORK(network))) {
+        virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return(-1);
+    }
+    virMutexLock(&network->conn->lock);
+    DEBUG("network=%p refs=%d", network, network->refs);
+    network->refs++;
+    virMutexUnlock(&network->conn->lock);
+    return 0;
+}
+
 /**
  * virNetworkGetName:
  * @network: a network object
@@ -5868,6 +5956,35 @@ virStoragePoolFree(virStoragePoolPtr pool)
 }
 
 
+/**
+ * virStoragePoolRef:
+ * @conn: the pool to hold a reference on
+ *
+ * Increment the reference count on the pool. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virStoragePoolFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection remain open until all threads have finished using
+ * it. ie, each new thread using a pool would increment
+ * the reference count.
+ */
+int
+virStoragePoolRef(virStoragePoolPtr pool)
+{
+    if ((!VIR_IS_CONNECTED_STORAGE_POOL(pool))) {
+        virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return(-1);
+    }
+    virMutexLock(&pool->conn->lock);
+    DEBUG("pool=%p refs=%d", pool, pool->refs);
+    pool->refs++;
+    virMutexUnlock(&pool->conn->lock);
+    return 0;
+}
+
 /**
  * virStoragePoolRefresh:
  * @pool: pointer to storage pool
@@ -6620,6 +6737,35 @@ virStorageVolFree(virStorageVolPtr vol)
 }
 
 
+/**
+ * virStorageVolRef:
+ * @conn: the vol to hold a reference on
+ *
+ * Increment the reference count on the vol. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virStorageVolFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection remain open until all threads have finished using
+ * it. ie, each new thread using a vol would increment
+ * the reference count.
+ */
+int
+virStorageVolRef(virStorageVolPtr vol)
+{
+    if ((!VIR_IS_CONNECTED_STORAGE_VOL(vol))) {
+        virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return(-1);
+    }
+    virMutexLock(&vol->conn->lock);
+    DEBUG("vol=%p refs=%d", vol, vol->refs);
+    vol->refs++;
+    virMutexUnlock(&vol->conn->lock);
+    return 0;
+}
+
 /**
  * virStorageVolGetInfo:
  * @vol: pointer to storage volume
@@ -7093,6 +7239,36 @@ int virNodeDeviceFree(virNodeDevicePtr dev)
 }
 
 
+/**
+ * virNodeDeviceRef:
+ * @conn: the dev to hold a reference on
+ *
+ * Increment the reference count on the dev. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virNodeDeviceFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection remain open until all threads have finished using
+ * it. ie, each new thread using a dev would increment
+ * the reference count.
+ */
+int
+virNodeDeviceRef(virNodeDevicePtr dev)
+{
+    if ((!VIR_IS_CONNECTED_NODE_DEVICE(dev))) {
+        virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return(-1);
+    }
+    virMutexLock(&dev->conn->lock);
+    DEBUG("dev=%p refs=%d", dev, dev->refs);
+    dev->refs++;
+    virMutexUnlock(&dev->conn->lock);
+    return 0;
+}
+
+
 /*
  * Domain Event Notification
  */
@@ -7107,6 +7283,13 @@ int virNodeDeviceFree(virNodeDevicePtr dev)
  * Adds a Domain Event Callback.
  * Registering for a domain callback will enable delivery of the events
  *
+ * The virDomainPtr object handle passed into the callback upon delivery
+ * of an event is only valid for the duration of execution of the callback.
+ * If the callback wishes to keep the domain object after the callback
+ * returns, it shall take a reference to it, by calling virDomainRef.
+ * The reference can be released once the object is no longer required
+ * by calling virDomainFree.
+ *
  * Returns 0 on success, -1 on failure
  */
 int

diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index be3fb4f737ff28388c44edf5ee17bbeb2b6d3d1a..0555c9074f73eed6c6ff3d43e455c4b4c4108b52 100644 (file)
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -236,5 +236,15 @@ LIBVIRT_0.5.0 {
 
 } LIBVIRT_0.4.5;
 
-# no new entry point in 0.5.1
+LIBVIRT_0.6.0 {
+    global:
+       virConnectRef;
+       virDomainRef;
+       virNetworkRef;
+       virStoragePoolRef;
+       virStorageVolRef;
+       virNodeDeviceRef;
+
+} LIBVIRT_0.5.0;
+
 # .... define new API here using predicted next version number ....