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 #define QOBJECT(obj) ({ \ 49 typeof(obj) _obj = (obj); \ 50 _obj ? container_of(&(_obj)->base, QObject, base) : NULL; \ 51 }) 52 53 /* Required for qobject_to() */ 54 #define QTYPE_CAST_TO_QNull QTYPE_QNULL 55 #define QTYPE_CAST_TO_QNum QTYPE_QNUM 56 #define QTYPE_CAST_TO_QString QTYPE_QSTRING 57 #define QTYPE_CAST_TO_QDict QTYPE_QDICT 58 #define QTYPE_CAST_TO_QList QTYPE_QLIST 59 #define QTYPE_CAST_TO_QBool QTYPE_QBOOL 60 61 QEMU_BUILD_BUG_MSG(QTYPE__MAX != 7, 62 "The QTYPE_CAST_TO_* list needs to be extended"); 63 64 #define qobject_to(type, obj) \ 65 ((type *)qobject_check_type(obj, glue(QTYPE_CAST_TO_, type))) 66 67 /* Initialize an object to default values */ 68 static inline void qobject_init(QObject *obj, QType type) 69 { 70 assert(QTYPE_NONE < type && type < QTYPE__MAX); 71 obj->base.refcnt = 1; 72 obj->base.type = type; 73 } 74 75 static inline void qobject_ref_impl(QObject *obj) 76 { 77 if (obj) { 78 obj->base.refcnt++; 79 } 80 } 81 82 /** 83 * qobject_is_equal(): Return whether the two objects are equal. 84 * 85 * Any of the pointers may be NULL; return true if both are. Always 86 * return false if only one is (therefore a QNull object is not 87 * considered equal to a NULL pointer). 88 */ 89 bool qobject_is_equal(const QObject *x, const QObject *y); 90 91 /** 92 * qobject_destroy(): Free resources used by the object 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 && --obj->base.refcnt == 0) { 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