External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-04 20:31:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
234a55604e
libvirt/src/util/virobject.h

91 lines
2.4 KiB
C
Raw Normal View History

Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
/*
* virobject.h: libvirt reference counted object
*
build: allow virObject to have no parent When building with static analysis enabled, we turn on attribute nonnull checking. However, this caused the build to fail with: ../../src/util/virobject.c: In function 'virObjectOnceInit': ../../src/util/virobject.c:55:40: error: null argument where non-null required (argument 1) [-Werror=nonnull] Creation of the virObject class is the one instance where the parent class is allowed to be NULL. Making things conditional will let us keep static analysis checking for all other .c file callers, without breaking the build on this one exception. * src/util/virobject.c: Define witness. * src/util/virobject.h (virClassNew): Use it to force most callers to pass non-null parameter.
2013-01-22 17:13:01 +00:00
* Copyright (C) 2012-2013 Red Hat, Inc.
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
maint: fix up copyright notice inconsistencies https://www.gnu.org/licenses/gpl-howto.html recommends that the 'If not, see <url>.' phrase be a separate sentence. * tests/securityselinuxhelper.c: Remove doubled line. * tests/securityselinuxtest.c: Likewise. * globally: s/; If/. If/
2012-09-20 22:30:55 +00:00
* License along with this library. If not, see
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
* <http://www.gnu.org/licenses/>.
*
*/
#ifndef __VIR_OBJECT_H__
# define __VIR_OBJECT_H__
# include "internal.h"
Add a virObjectLockable class holding a mutex A great many virObject instances require a mutex, so introduce a convenient class for this which provides a mutex. This avoids repeating the tedious init/destroy code Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:54:07 +00:00
# include "virthread.h"
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
typedef struct _virClass virClass;
typedef virClass *virClassPtr;
typedef struct _virObject virObject;
typedef virObject *virObjectPtr;
Add a virObjectLockable class holding a mutex A great many virObject instances require a mutex, so introduce a convenient class for this which provides a mutex. This avoids repeating the tedious init/destroy code Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:54:07 +00:00
typedef struct _virObjectLockable virObjectLockable;
typedef virObjectLockable *virObjectLockablePtr;
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
typedef void (*virObjectDisposeCallback)(void *obj);
struct _virObject {
unsigned int magic;
int refs;
virClassPtr klass;
};
Add a virObjectLockable class holding a mutex A great many virObject instances require a mutex, so introduce a convenient class for this which provides a mutex. This avoids repeating the tedious init/destroy code Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:54:07 +00:00
struct _virObjectLockable {
virObject parent;
virMutex lock;
};
Allow for multi-level inheritance of virObject classes Currently all classes must directly inherit from virObject. This allows for arbitrarily deep hierarchy. There's not much to this aside from chaining up the 'dispose' handlers from each class & providing APIs to check types. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:37:27 +00:00
virClassPtr virClassForObject(void);
Add a virObjectLockable class holding a mutex A great many virObject instances require a mutex, so introduce a convenient class for this which provides a mutex. This avoids repeating the tedious init/destroy code Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:54:07 +00:00
virClassPtr virClassForObjectLockable(void);
Allow for multi-level inheritance of virObject classes Currently all classes must directly inherit from virObject. This allows for arbitrarily deep hierarchy. There's not much to this aside from chaining up the 'dispose' handlers from each class & providing APIs to check types. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:37:27 +00:00
build: allow virObject to have no parent When building with static analysis enabled, we turn on attribute nonnull checking. However, this caused the build to fail with: ../../src/util/virobject.c: In function 'virObjectOnceInit': ../../src/util/virobject.c:55:40: error: null argument where non-null required (argument 1) [-Werror=nonnull] Creation of the virObject class is the one instance where the parent class is allowed to be NULL. Making things conditional will let us keep static analysis checking for all other .c file callers, without breaking the build on this one exception. * src/util/virobject.c: Define witness. * src/util/virobject.h (virClassNew): Use it to force most callers to pass non-null parameter.
2013-01-22 17:13:01 +00:00
# ifndef VIR_PARENT_REQUIRED
# define VIR_PARENT_REQUIRED ATTRIBUTE_NONNULL(1)
# endif
Allow for multi-level inheritance of virObject classes Currently all classes must directly inherit from virObject. This allows for arbitrarily deep hierarchy. There's not much to this aside from chaining up the 'dispose' handlers from each class & providing APIs to check types. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:37:27 +00:00
virClassPtr virClassNew(virClassPtr parent,
const char *name,
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
size_t objectSize,
virObjectDisposeCallback dispose)
build: allow virObject to have no parent When building with static analysis enabled, we turn on attribute nonnull checking. However, this caused the build to fail with: ../../src/util/virobject.c: In function 'virObjectOnceInit': ../../src/util/virobject.c:55:40: error: null argument where non-null required (argument 1) [-Werror=nonnull] Creation of the virObject class is the one instance where the parent class is allowed to be NULL. Making things conditional will let us keep static analysis checking for all other .c file callers, without breaking the build on this one exception. * src/util/virobject.c: Define witness. * src/util/virobject.h (virClassNew): Use it to force most callers to pass non-null parameter.
2013-01-22 17:13:01 +00:00
VIR_PARENT_REQUIRED ATTRIBUTE_NONNULL(2);
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
const char *virClassName(virClassPtr klass)
ATTRIBUTE_NONNULL(1);
Allow for multi-level inheritance of virObject classes Currently all classes must directly inherit from virObject. This allows for arbitrarily deep hierarchy. There's not much to this aside from chaining up the 'dispose' handlers from each class & providing APIs to check types. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:37:27 +00:00
bool virClassIsDerivedFrom(virClassPtr klass,
virClassPtr parent)
ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
void *virObjectNew(virClassPtr klass)
ATTRIBUTE_NONNULL(1);
bool virObjectUnref(void *obj);
void *virObjectRef(void *obj);
bool virObjectIsClass(void *obj,
virClassPtr klass)
ATTRIBUTE_NONNULL(2);
void virObjectFreeCallback(void *opaque);
Add a virObjectLockable class holding a mutex A great many virObject instances require a mutex, so introduce a convenient class for this which provides a mutex. This avoids repeating the tedious init/destroy code Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-09 17:54:07 +00:00
void *virObjectLockableNew(virClassPtr klass)
ATTRIBUTE_NONNULL(1);
void virObjectLock(void *lockableobj)
ATTRIBUTE_NONNULL(1);
void virObjectUnlock(void *lockableobj)
ATTRIBUTE_NONNULL(1);
Add a generic reference counted virObject type This introduces a fairly basic reference counted virObject type and an associated virClass type, that use atomic operations for ref counting. In a global initializer (recommended to be invoked using the virOnceInit API), a virClass type must be allocated for each object type. This requires a class name, a "dispose" callback which will be invoked to free memory associated with the object's fields, and the size in bytes of the object struct. eg, virClassPtr connclass = virClassNew("virConnect", sizeof(virConnect), virConnectDispose); The struct for the object, must include 'virObject' as its first member eg struct _virConnect { virObject object; virURIPtr uri; }; The 'dispose' callback is only responsible for freeing fields in the object, not the object itself. eg a suitable impl for the above struct would be void virConnectDispose(void *obj) { virConnectPtr conn = obj; virURIFree(conn->uri); } There is no need to reset fields to 'NULL' or '0' in the dispose callback, since the entire object will be memset to 0, and the klass pointer & magic integer fields will be poisoned with 0xDEADBEEF before being free()d When creating an instance of an object, one needs simply pass the virClassPtr eg virConnectPtr conn = virObjectNew(connclass); if (!conn) return NULL; conn->uri = virURIParse("foo:///bar") Object references can be manipulated with virObjectRef(conn) virObjectUnref(conn) The latter returns a true value, if the object has been freed (ie its ref count hit zero) Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-07-11 13:35:44 +00:00
#endif /* __VIR_OBJECT_H */
Reference in New Issue Copy Permalink