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