External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-10-06 22:35:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
a771351ae4
libvirt/src/util/virobject.h

162 lines
4.0 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
*
hash: add common utility functions I almost wrote a hash value free function that just called VIR_FREE, then realized I couldn't be the first person to do that. Sure enough, it was worth factoring into a common helper routine. * src/util/virhash.h (virHashValueFree): New function. * src/util/virhash.c (virHashValueFree): Implement it. * src/util/virobject.h (virObjectFreeHashData): New function. * src/libvirt_private.syms (virhash.h, virobject.h): Export them. * src/nwfilter/nwfilter_learnipaddr.c (virNWFilterLearnInit): Use common function. * src/qemu/qemu_capabilities.c (virQEMUCapsCacheNew): Likewise. * src/qemu/qemu_command.c (qemuDomainCCWAddressSetCreate): Likewise. * src/qemu/qemu_monitor.c (qemuMonitorGetBlockInfo): Likewise. * src/qemu/qemu_process.c (qemuProcessWaitForMonitor): Likewise. * src/util/virclosecallbacks.c (virCloseCallbacksNew): Likewise. * src/util/virkeyfile.c (virKeyFileParseGroup): Likewise. * tests/qemumonitorjsontest.c (testQemuMonitorJSONqemuMonitorJSONGetBlockInfo): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2014-04-04 23:36:25 +00:00
* Copyright (C) 2012-2014 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/>.
*
*/
util: object: use #pragma once in headers Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com> Signed-off-by: Ján Tomko <jtomko@redhat.com>
2019-06-18 16:13:01 +00:00
#pragma once
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
util: object: use #pragma once in headers Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com> Signed-off-by: Ján Tomko <jtomko@redhat.com>
2019-06-18 16:13:01 +00:00
#include "internal.h"
#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;
virobject: Introduce virObjectRWLockable Up until now we only had virObjectLockable which uses mutexes for mutually excluding each other in critical section. Well, this is not enough. Future work will require RW locks so we might as well have virObjectRWLockable which is introduced here. Moreover, polymorphism is introduced to our code for the first time. Yay! More specifically, virObjectLock will grab a write lock, virObjectLockRead will grab a read lock then (what a surprise right?). This has great advantage that an object can be made derived from virObjectRWLockable in a single line and still continue functioning properly (mutexes can be viewed as grabbing write locks only). Then just those critical sections that can grab a read lock need fixing. Therefore the resulting change is going to be way smaller. In order to avoid writer starvation, the object initializes RW lock that prefers writers. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2017-07-19 07:31:50 +00:00
typedef struct _virObjectRWLockable virObjectRWLockable;
typedef virObjectRWLockable *virObjectRWLockablePtr;
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);
object: require maximal alignment in base class Recent changes to events (commit 8a29ffcf) resulted in new compile failures on some targets (such as ARM OMAP5): conf/domain_event.c: In function 'virDomainEventDispatchDefaultFunc': conf/domain_event.c:1198:30: error: cast increases required alignment of target type [-Werror=cast-align] conf/domain_event.c:1314:34: error: cast increases required alignment of target type [-Werror=cast-align] cc1: all warnings being treated as errors The error is due to alignment; the base class is merely aligned to the worst of 'int' and 'void*', while the child class must be aligned to a 'long long'. The solution is to include a 'long long' (and for good measure, a function pointer) in the base class to ensure correct alignment regardless of what a child class may add, but to wrap the inclusion in a union so as to not incur any wasted space. On a typical x86_64 platform, the base class remains 16 bytes; on i686, the base class remains 12 bytes; and on the impacted ARM platform, the base class grows from 12 bytes to 16 bytes due to the increase of alignment from 4 to 8 bytes. Reported by Michele Paolino and others. * src/util/virobject.h (_virObject): Use a union to ensure that subclasses never have stricter alignment than the parent. * src/util/virobject.c (virObjectNew, virObjectUnref) (virObjectRef): Adjust clients. * src/libvirt.c (virConnectRef, virDomainRef, virNetworkRef) (virInterfaceRef, virStoragePoolRef, virStorageVolRef) (virNodeDeviceRef, virSecretRef, virStreamRef, virNWFilterRef) (virDomainSnapshotRef): Likewise. * src/qemu/qemu_monitor.c (qemuMonitorOpenInternal) (qemuMonitorClose): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-12 23:01:15 +00:00
/* Most code should not play with the contents of this struct; however,
* the struct itself is public so that it can be embedded as the first
* field of a subclassed object. */
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
struct _virObject {
object: require maximal alignment in base class Recent changes to events (commit 8a29ffcf) resulted in new compile failures on some targets (such as ARM OMAP5): conf/domain_event.c: In function 'virDomainEventDispatchDefaultFunc': conf/domain_event.c:1198:30: error: cast increases required alignment of target type [-Werror=cast-align] conf/domain_event.c:1314:34: error: cast increases required alignment of target type [-Werror=cast-align] cc1: all warnings being treated as errors The error is due to alignment; the base class is merely aligned to the worst of 'int' and 'void*', while the child class must be aligned to a 'long long'. The solution is to include a 'long long' (and for good measure, a function pointer) in the base class to ensure correct alignment regardless of what a child class may add, but to wrap the inclusion in a union so as to not incur any wasted space. On a typical x86_64 platform, the base class remains 16 bytes; on i686, the base class remains 12 bytes; and on the impacted ARM platform, the base class grows from 12 bytes to 16 bytes due to the increase of alignment from 4 to 8 bytes. Reported by Michele Paolino and others. * src/util/virobject.h (_virObject): Use a union to ensure that subclasses never have stricter alignment than the parent. * src/util/virobject.c (virObjectNew, virObjectUnref) (virObjectRef): Adjust clients. * src/libvirt.c (virConnectRef, virDomainRef, virNetworkRef) (virInterfaceRef, virStoragePoolRef, virStorageVolRef) (virNodeDeviceRef, virSecretRef, virStreamRef, virNWFilterRef) (virDomainSnapshotRef): Likewise. * src/qemu/qemu_monitor.c (qemuMonitorOpenInternal) (qemuMonitorClose): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-12 23:01:15 +00:00
/* Ensure correct alignment of this and all subclasses, even on
* platforms where 'long long' or function pointers have stricter
* requirements than 'void *'. */
union {
long long dummy_align1;
void (*dummy_align2) (void);
struct {
unsigned int magic;
int refs;
} s;
} u;
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
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;
};
virobject: Introduce virObjectRWLockable Up until now we only had virObjectLockable which uses mutexes for mutually excluding each other in critical section. Well, this is not enough. Future work will require RW locks so we might as well have virObjectRWLockable which is introduced here. Moreover, polymorphism is introduced to our code for the first time. Yay! More specifically, virObjectLock will grab a write lock, virObjectLockRead will grab a read lock then (what a surprise right?). This has great advantage that an object can be made derived from virObjectRWLockable in a single line and still continue functioning properly (mutexes can be viewed as grabbing write locks only). Then just those critical sections that can grab a read lock need fixing. Therefore the resulting change is going to be way smaller. In order to avoid writer starvation, the object initializes RW lock that prefers writers. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2017-07-19 07:31:50 +00:00
struct _virObjectRWLockable {
virObject parent;
virRWLock lock;
};
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
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);
virobject: Introduce virObjectRWLockable Up until now we only had virObjectLockable which uses mutexes for mutually excluding each other in critical section. Well, this is not enough. Future work will require RW locks so we might as well have virObjectRWLockable which is introduced here. Moreover, polymorphism is introduced to our code for the first time. Yay! More specifically, virObjectLock will grab a write lock, virObjectLockRead will grab a read lock then (what a surprise right?). This has great advantage that an object can be made derived from virObjectRWLockable in a single line and still continue functioning properly (mutexes can be viewed as grabbing write locks only). Then just those critical sections that can grab a read lock need fixing. Therefore the resulting change is going to be way smaller. In order to avoid writer starvation, the object initializes RW lock that prefers writers. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2017-07-19 07:31:50 +00:00
virClassPtr virClassForObjectRWLockable(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
util: object: use #pragma once in headers Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com> Signed-off-by: Ján Tomko <jtomko@redhat.com>
2019-06-18 16:13:01 +00:00
#ifndef VIR_PARENT_REQUIRED
# define VIR_PARENT_REQUIRED ATTRIBUTE_NONNULL(1)
#endif
virobject: Introduce VIR_CLASS_NEW() macro So far we are repeating the following lines over and over: if (!(virSomeObjectClass = virClassNew(virClassForObject(), "virSomeObject", sizeof(virSomeObject), virSomeObjectDispose))) return -1; While this works, it is impossible to do some checking. Firstly, the class name (the 2nd argument) doesn't match the name in the code in all cases (the 3rd argument). Secondly, the current style is needlessly verbose. This commit turns example into following: if (!(VIR_CLASS_NEW(virSomeObject, virClassForObject))) return -1; Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-04-17 15:42:33 +00:00
virobject: Improve documentation I had to inspect the code to learn whether a final virObjectUnref() calls ALL dispose callbacks in child-to-parent order (akin to C++ destructors), or whether I manually had to call a parent-class dispose when writing a child class dispose method. The answer is the former. (Thankfully, since VIR_FREE wipes out pointers for safety, even if I had guessed wrong, I probably would not have tripped over a double-free fault when the parent dispose ran for the second time). I also had to read the code to learn if a dispose method was even mandatory (it is not, although getting NULL through VIR_CLASS_NEW requires a macro). While at it, the VIR_CLASS_NEW macro requires that the virObject component at offset 0 be reached through the name 'parent', not 'object'. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
2019-03-15 04:14:41 +00:00
/* Assign the class description nameClass to represent struct @name
* (which must have an object-based 'parent' member at offset 0), and
* with parent class @prnt. nameDispose must exist as either a
* function or as a macro defined to NULL.
*/
util: object: use #pragma once in headers Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com> Signed-off-by: Ján Tomko <jtomko@redhat.com>
2019-06-18 16:13:01 +00:00
#define VIR_CLASS_NEW(name, prnt) \
src: replace verify(expr) with G_STATIC_ASSERT(expr) G_STATIC_ASSERT() is a drop-in functional equivalent of the GNULIB verify() macro. Reviewed-by: Pavel Hrdina <phrdina@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-01-09 10:39:55 +00:00
(G_STATIC_ASSERT_EXPR(offsetof(name, parent) == 0), \
(name##Class = virClassNew(prnt, #name, sizeof(name),\
sizeof(((name *)NULL)->parent), \
name##Dispose)))
virobject: Introduce VIR_CLASS_NEW() macro So far we are repeating the following lines over and over: if (!(virSomeObjectClass = virClassNew(virClassForObject(), "virSomeObject", sizeof(virSomeObject), virSomeObjectDispose))) return -1; While this works, it is impossible to do some checking. Firstly, the class name (the 2nd argument) doesn't match the name in the code in all cases (the 3rd argument). Secondly, the current style is needlessly verbose. This commit turns example into following: if (!(VIR_CLASS_NEW(virSomeObject, virClassForObject))) return -1; Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-04-17 15:42:33 +00:00
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
virClassPtr
virClassNew(virClassPtr parent,
const char *name,
size_t objectSize,
object: Add sanity check on correct parent class Checking that the derived class is larger than the requested parent class saves us from some obvious mistakes, but as written, it does not catch all the cases; in particular, it is easy to forget to update a VIR_CLASS_NEW when changing the 'parent' member from virObject to virObjectLockabale, but where the size checks don't catch that. Add a parameter for one more layer of sanity checking. It would be cool if we could get gcc to stringize typeof(parent) into the string name of that type, so that we could confirm that the precise parent class is in use rather than just a struct that happens to have the same size as the parent class. But sizeof checks are better than nothing. Note that I did NOT change the fact that we require derived classes to be larger (as the difference in size makes it easy to tell classes apart), which means that even if a derived class has no functionality to add (but rather exists for compiler-enforced type-safety), it must still include a dummy member. But I did fix the wording of the error message to match the code. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-03-15 14:41:18 +00:00
size_t parentSize,
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
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
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
const char *
virClassName(virClassPtr klass)
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
ATTRIBUTE_NONNULL(1);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
bool
virClassIsDerivedFrom(virClassPtr klass,
virClassPtr parent)
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
ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void *
virObjectNew(virClassPtr klass)
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
ATTRIBUTE_NONNULL(1);
src: make virObjectUnref return void To prepare for a conversion to GObject, we need virObjectUnref to have the same API design as g_object_unref, which means it needs to be void. A few places do actually care about the return value though, and in these cases a thread local flag is used to determine if the dispose method was invoked. Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-05-15 15:36:00 +00:00
void
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
virObjectUnref(void *obj);
src: add support for g_autoptr with virObject instances Libvirt currently uses the VIR_AUTOUNREF macro for auto cleanup of virObject instances. GLib approaches things differently with GObject, reusing their g_autoptr() concept. This introduces support for g_autoptr() with virObject, to facilitate the conversion to GObject. Only virObject classes which are currently used with VIR_AUTOREF are updated. Any others should be converted to GObject before introducing use of autocleanup. Reviewed-by: Ján Tomko <jtomko@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-10-04 16:14:10 +00:00
G_DEFINE_AUTOPTR_CLEANUP_FUNC(virObject, virObjectUnref);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void *
virObjectRef(void *obj);
bool
virObjectIsClass(void *obj,
virClassPtr klass)
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
ATTRIBUTE_NONNULL(2);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void
virObjectFreeCallback(void *opaque);
void
util: consolidate on one free callback for hash data This previous commit introduced a simpler free callback for hash data with only 1 arg, the value to free: commit 49288fac965f0ee23db45d83ae4ef3a9a71dafd0 Author: Peter Krempa <pkrempa@redhat.com> Date: Wed Oct 9 15:26:37 2019 +0200 util: hash: Add possibility to use simpler data free function in virHash It missed two functions in the hash table code which need to call the alternate data free function, virHashRemoveEntry and virHashRemoveSet. After the previous patch though, there is no code that makes functional use of the 2nd key arg in the data free function. There is merely one log message that can be dropped. We can thus purge the current virHashDataFree callback entirely, and rename virHashDataFreeSimple to replace it. Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-11-21 19:27:58 +00:00
virObjectFreeHashData(void *opaque);
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
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void *
virObjectLockableNew(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
ATTRIBUTE_NONNULL(1);
virobject: Introduce virObjectRWLockable Up until now we only had virObjectLockable which uses mutexes for mutually excluding each other in critical section. Well, this is not enough. Future work will require RW locks so we might as well have virObjectRWLockable which is introduced here. Moreover, polymorphism is introduced to our code for the first time. Yay! More specifically, virObjectLock will grab a write lock, virObjectLockRead will grab a read lock then (what a surprise right?). This has great advantage that an object can be made derived from virObjectRWLockable in a single line and still continue functioning properly (mutexes can be viewed as grabbing write locks only). Then just those critical sections that can grab a read lock need fixing. Therefore the resulting change is going to be way smaller. In order to avoid writer starvation, the object initializes RW lock that prefers writers. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2017-07-19 07:31:50 +00:00
void *
virObjectRWLockableNew(virClassPtr klass)
ATTRIBUTE_NONNULL(1);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void
virObjectLock(void *lockableobj)
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
ATTRIBUTE_NONNULL(1);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
virobject: Introduce virObjectRWLockable Up until now we only had virObjectLockable which uses mutexes for mutually excluding each other in critical section. Well, this is not enough. Future work will require RW locks so we might as well have virObjectRWLockable which is introduced here. Moreover, polymorphism is introduced to our code for the first time. Yay! More specifically, virObjectLock will grab a write lock, virObjectLockRead will grab a read lock then (what a surprise right?). This has great advantage that an object can be made derived from virObjectRWLockable in a single line and still continue functioning properly (mutexes can be viewed as grabbing write locks only). Then just those critical sections that can grab a read lock need fixing. Therefore the resulting change is going to be way smaller. In order to avoid writer starvation, the object initializes RW lock that prefers writers. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2017-07-19 07:31:50 +00:00
void
util: Rename virObjectLockRead to virObjectRWLockRead Since the class it represents is based on virObjectRWLockableClass and in order to make sure we differentiate just in case anyone somehow believes they could use virObjectLockRead for a virObjectLockableClass, let's rename the API to use the RW in the name. Besides the RW locks refer to pthread_rwlock_{init|rdlock|wrlock|unlock|destroy} while the other locks refer to pthread_mutex_{init|lock|unlock|destroy}. Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-07-28 13:57:04 +00:00
virObjectRWLockRead(void *lockableobj)
virobject: Introduce virObjectRWLockable Up until now we only had virObjectLockable which uses mutexes for mutually excluding each other in critical section. Well, this is not enough. Future work will require RW locks so we might as well have virObjectRWLockable which is introduced here. Moreover, polymorphism is introduced to our code for the first time. Yay! More specifically, virObjectLock will grab a write lock, virObjectLockRead will grab a read lock then (what a surprise right?). This has great advantage that an object can be made derived from virObjectRWLockable in a single line and still continue functioning properly (mutexes can be viewed as grabbing write locks only). Then just those critical sections that can grab a read lock need fixing. Therefore the resulting change is going to be way smaller. In order to avoid writer starvation, the object initializes RW lock that prefers writers. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2017-07-19 07:31:50 +00:00
ATTRIBUTE_NONNULL(1);
util: Introduce and use virObjectRWLockWrite Instead of making virObjectLock be the entry point for two different types of locks, let's create a virObjectRWLockWrite API which will only handle the virObjectRWLockableClass objects. Use the new virObjectRWLockWrite for the virdomainobjlist code in order to handle the Add, Remove, Rename, and Load operations that need to be very synchronous. Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-07-28 14:06:55 +00:00
void
virObjectRWLockWrite(void *lockableobj)
ATTRIBUTE_NONNULL(1);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void
virObjectUnlock(void *lockableobj)
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
ATTRIBUTE_NONNULL(1);
util: Introduce and use virObjectRWUnlock Rather than overload virObjectUnlock as commit id '77f4593b' has done, create a separate virObjectRWUnlock API that will force the consumers to make the proper decision regarding unlocking the RWLock's. Similar to the RWLockRead and RWLockWrite, use the virObjectGetRWLockableObj helper. This restores the virObjectUnlock code to using the virObjectGetLockableObj. Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-07-28 16:03:50 +00:00
void
virObjectRWUnlock(void *lockableobj)
ATTRIBUTE_NONNULL(1);
util: Formatting cleanups to virobject API Alter to use more recent formatting guidelines Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-03-28 19:09:55 +00:00
void
virObjectListFree(void *list);
void
virObjectListFreeCount(void *list,
size_t count);
Reference in New Issue Copy Permalink