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 "qemu/atomic.h" 36 #include "qapi/qapi-builtin-types.h" 37 38 /* Not for use outside include/qobject/ */ 39 struct QObjectBase_ { 40 QType type; 41 size_t refcnt; 42 }; 43 44 /* this struct must have no other members than base */ 45 struct QObject { 46 struct QObjectBase_ base; 47 }; 48 49 /* 50 * Preprocessor sorcery ahead: use a different identifier for the 51 * local variable in each expansion, so we can nest macro calls 52 * without shadowing variables. 53 */ 54 #define QOBJECT_INTERNAL(obj, _obj) ({ \ 55 typeof(obj) _obj = (obj); \ 56 _obj ? container_of(&_obj->base, QObject, base) : NULL; \ 57 }) 58 #define QOBJECT(obj) QOBJECT_INTERNAL((obj), MAKE_IDENTIFIER(_obj)) 59 60 /* Required for qobject_to() */ 61 #define QTYPE_CAST_TO_QNull QTYPE_QNULL 62 #define QTYPE_CAST_TO_QNum QTYPE_QNUM 63 #define QTYPE_CAST_TO_QString QTYPE_QSTRING 64 #define QTYPE_CAST_TO_QDict QTYPE_QDICT 65 #define QTYPE_CAST_TO_QList QTYPE_QLIST 66 #define QTYPE_CAST_TO_QBool QTYPE_QBOOL 67 68 QEMU_BUILD_BUG_MSG(QTYPE__MAX != 7, 69 "The QTYPE_CAST_TO_* list needs to be extended"); 70 71 #define qobject_to(type, obj) \ 72 ((type *)qobject_check_type(obj, glue(QTYPE_CAST_TO_, type))) 73 74 static inline void qobject_ref_impl(QObject *obj) 75 { 76 if (obj) { 77 qatomic_inc(&obj->base.refcnt); 78 } 79 } 80 81 /** 82 * qobject_is_equal(): Return whether the two objects are equal. 83 * 84 * Any of the pointers may be NULL; return true if both are. Always 85 * return false if only one is (therefore a QNull object is not 86 * considered equal to a NULL pointer). 87 */ 88 bool qobject_is_equal(const QObject *x, const QObject *y); 89 90 /** 91 * qobject_destroy(): Free resources used by the object 92 * For use via qobject_unref() only! 93 */ 94 void qobject_destroy(QObject *obj); 95 96 static inline void qobject_unref_impl(QObject *obj) 97 { 98 assert(!obj || obj->base.refcnt); 99 if (obj && qatomic_fetch_dec(&obj->base.refcnt) == 1) { 100 qobject_destroy(obj); 101 } 102 } 103 104 /** 105 * qobject_ref(): Increment QObject's reference count 106 * 107 * Returns: the same @obj. The type of @obj will be propagated to the 108 * return type. 109 */ 110 #define qobject_ref(obj) ({ \ 111 typeof(obj) _o = (obj); \ 112 qobject_ref_impl(QOBJECT(_o)); \ 113 _o; \ 114 }) 115 116 /** 117 * qobject_unref(): Decrement QObject's reference count, deallocate 118 * when it reaches zero 119 */ 120 #define qobject_unref(obj) qobject_unref_impl(QOBJECT(obj)) 121 122 /** 123 * qobject_type(): Return the QObject's type 124 */ 125 static inline QType qobject_type(const QObject *obj) 126 { 127 assert(QTYPE_NONE < obj->base.type && obj->base.type < QTYPE__MAX); 128 return obj->base.type; 129 } 130 131 /** 132 * qobject_check_type(): Helper function for the qobject_to() macro. 133 * Return @obj, but only if @obj is not NULL and @type is equal to 134 * @obj's type. Return NULL otherwise. 135 */ 136 static inline QObject *qobject_check_type(const QObject *obj, QType type) 137 { 138 if (obj && qobject_type(obj) == type) { 139 return (QObject *)obj; 140 } else { 141 return NULL; 142 } 143 } 144 145 #endif /* QOBJECT_H */ 146