qobject.h (4061B)
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 static inline void qobject_ref_impl(QObject *obj) 68 { 69 if (obj) { 70 obj->base.refcnt++; 71 } 72 } 73 74 /** 75 * qobject_is_equal(): Return whether the two objects are equal. 76 * 77 * Any of the pointers may be NULL; return true if both are. Always 78 * return false if only one is (therefore a QNull object is not 79 * considered equal to a NULL pointer). 80 */ 81 bool qobject_is_equal(const QObject *x, const QObject *y); 82 83 /** 84 * qobject_destroy(): Free resources used by the object 85 * For use via qobject_unref() only! 86 */ 87 void qobject_destroy(QObject *obj); 88 89 static inline void qobject_unref_impl(QObject *obj) 90 { 91 assert(!obj || obj->base.refcnt); 92 if (obj && --obj->base.refcnt == 0) { 93 qobject_destroy(obj); 94 } 95 } 96 97 /** 98 * qobject_ref(): Increment QObject's reference count 99 * 100 * Returns: the same @obj. The type of @obj will be propagated to the 101 * return type. 102 */ 103 #define qobject_ref(obj) ({ \ 104 typeof(obj) _o = (obj); \ 105 qobject_ref_impl(QOBJECT(_o)); \ 106 _o; \ 107 }) 108 109 /** 110 * qobject_unref(): Decrement QObject's reference count, deallocate 111 * when it reaches zero 112 */ 113 #define qobject_unref(obj) qobject_unref_impl(QOBJECT(obj)) 114 115 /** 116 * qobject_type(): Return the QObject's type 117 */ 118 static inline QType qobject_type(const QObject *obj) 119 { 120 assert(QTYPE_NONE < obj->base.type && obj->base.type < QTYPE__MAX); 121 return obj->base.type; 122 } 123 124 /** 125 * qobject_check_type(): Helper function for the qobject_to() macro. 126 * Return @obj, but only if @obj is not NULL and @type is equal to 127 * @obj's type. Return NULL otherwise. 128 */ 129 static inline QObject *qobject_check_type(const QObject *obj, QType type) 130 { 131 if (obj && qobject_type(obj) == type) { 132 return (QObject *)obj; 133 } else { 134 return NULL; 135 } 136 } 137 138 #endif /* QOBJECT_H */