1 /* 2 * QEMU Object Model. 3 * 4 * Based on ideas by Avi Kivity <avi@redhat.com> 5 * 6 * Copyright (C) 2009, 2015 Red Hat Inc. 7 * 8 * Authors: 9 * Luiz Capitulino <lcapitulino@redhat.com> 10 * 11 * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. 12 * See the COPYING.LIB file in the top-level directory. 13 * 14 * QObject Reference Counts Terminology 15 * ------------------------------------ 16 * 17 * - Returning references: A function that returns an object may 18 * return it as either a weak or a strong reference. If the 19 * reference is strong, you are responsible for calling 20 * qobject_unref() on the reference when you are done. 21 * 22 * If the reference is weak, the owner of the reference may free it at 23 * any time in the future. Before storing the reference anywhere, you 24 * should call qobject_ref() to make the reference strong. 25 * 26 * - Transferring ownership: when you transfer ownership of a reference 27 * by calling a function, you are no longer responsible for calling 28 * qobject_unref() when the reference is no longer needed. In other words, 29 * when the function returns you must behave as if the reference to the 30 * passed object was weak. 31 */ 32 #ifndef QOBJECT_H 33 #define QOBJECT_H 34 35 #include "qapi/qapi-builtin-types.h" 36 37 /* Not for use outside include/qapi/qmp/ */ 38 struct QObjectBase_ { 39 QType type; 40 size_t refcnt; 41 }; 42 43 /* this struct must have no other members than base */ 44 struct QObject { 45 struct QObjectBase_ base; 46 }; 47 48 /* 49 * Preprocessor sorcery ahead: use a different identifier for the 50 * local variable in each expansion, so we can nest macro calls 51 * without shadowing variables. 52 */ 53 #define QOBJECT_INTERNAL(obj, _obj) ({ \ 54 typeof(obj) _obj = (obj); \ 55 _obj ? container_of(&_obj->base, QObject, base) : NULL; \ 56 }) 57 #define QOBJECT(obj) QOBJECT_INTERNAL((obj), MAKE_IDENTFIER(_obj)) 58 59 /* Required for qobject_to() */ 60 #define QTYPE_CAST_TO_QNull QTYPE_QNULL 61 #define QTYPE_CAST_TO_QNum QTYPE_QNUM 62 #define QTYPE_CAST_TO_QString QTYPE_QSTRING 63 #define QTYPE_CAST_TO_QDict QTYPE_QDICT 64 #define QTYPE_CAST_TO_QList QTYPE_QLIST 65 #define QTYPE_CAST_TO_QBool QTYPE_QBOOL 66 67 QEMU_BUILD_BUG_MSG(QTYPE__MAX != 7, 68 "The QTYPE_CAST_TO_* list needs to be extended"); 69 70 #define qobject_to(type, obj) \ 71 ((type *)qobject_check_type(obj, glue(QTYPE_CAST_TO_, type))) 72 73 static inline void qobject_ref_impl(QObject *obj) 74 { 75 if (obj) { 76 obj->base.refcnt++; 77 } 78 } 79 80 /** 81 * qobject_is_equal(): Return whether the two objects are equal. 82 * 83 * Any of the pointers may be NULL; return true if both are. Always 84 * return false if only one is (therefore a QNull object is not 85 * considered equal to a NULL pointer). 86 */ 87 bool qobject_is_equal(const QObject *x, const QObject *y); 88 89 /** 90 * qobject_destroy(): Free resources used by the object 91 * For use via qobject_unref() only! 92 */ 93 void qobject_destroy(QObject *obj); 94 95 static inline void qobject_unref_impl(QObject *obj) 96 { 97 assert(!obj || obj->base.refcnt); 98 if (obj && --obj->base.refcnt == 0) { 99 qobject_destroy(obj); 100 } 101 } 102 103 /** 104 * qobject_ref(): Increment QObject's reference count 105 * 106 * Returns: the same @obj. The type of @obj will be propagated to the 107 * return type. 108 */ 109 #define qobject_ref(obj) ({ \ 110 typeof(obj) _o = (obj); \ 111 qobject_ref_impl(QOBJECT(_o)); \ 112 _o; \ 113 }) 114 115 /** 116 * qobject_unref(): Decrement QObject's reference count, deallocate 117 * when it reaches zero 118 */ 119 #define qobject_unref(obj) qobject_unref_impl(QOBJECT(obj)) 120 121 /** 122 * qobject_type(): Return the QObject's type 123 */ 124 static inline QType qobject_type(const QObject *obj) 125 { 126 assert(QTYPE_NONE < obj->base.type && obj->base.type < QTYPE__MAX); 127 return obj->base.type; 128 } 129 130 /** 131 * qobject_check_type(): Helper function for the qobject_to() macro. 132 * Return @obj, but only if @obj is not NULL and @type is equal to 133 * @obj's type. Return NULL otherwise. 134 */ 135 static inline QObject *qobject_check_type(const QObject *obj, QType type) 136 { 137 if (obj && qobject_type(obj) == type) { 138 return (QObject *)obj; 139 } else { 140 return NULL; 141 } 142 } 143 144 #endif /* QOBJECT_H */ 145