| 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 */ |