Annotation of qemu/qobject.h, revision 1.1.1.1

1.1       root        1: /*
                      2:  * QEMU Object Model.
                      3:  *
                      4:  * Based on ideas by Avi Kivity <avi@redhat.com>
                      5:  *
                      6:  * Copyright (C) 2009 Red Hat Inc.
                      7:  *
                      8:  * Authors:
                      9:  *  Luiz Capitulino <lcapitulino@redhat.com>
                     10:  *
                     11:  * This work is licensed under the terms of the GNU GPL, version 2.  See
                     12:  * the COPYING 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 reference
                     19:  *  is strong, you are responsible for calling QDECREF() on the reference
                     20:  *  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 QINCREF() 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:  *  QDECREF() 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 <stddef.h>
                     36: #include <assert.h>
                     37: 
                     38: typedef enum {
                     39:     QTYPE_NONE,
                     40:     QTYPE_QINT,
                     41:     QTYPE_QSTRING,
                     42:     QTYPE_QDICT,
                     43:     QTYPE_QLIST,
                     44:     QTYPE_QFLOAT,
                     45:     QTYPE_QBOOL,
                     46:     QTYPE_QERROR,
                     47: } qtype_code;
                     48: 
                     49: struct QObject;
                     50: 
                     51: typedef struct QType {
                     52:     qtype_code code;
                     53:     void (*destroy)(struct QObject *);
                     54: } QType;
                     55: 
                     56: typedef struct QObject {
                     57:     const QType *type;
                     58:     size_t refcnt;
                     59: } QObject;
                     60: 
                     61: /* Objects definitions must include this */
                     62: #define QObject_HEAD  \
                     63:     QObject base
                     64: 
                     65: /* Get the 'base' part of an object */
                     66: #define QOBJECT(obj) (&(obj)->base)
                     67: 
                     68: /* High-level interface for qobject_incref() */
                     69: #define QINCREF(obj)      \
                     70:     qobject_incref(QOBJECT(obj))
                     71: 
                     72: /* High-level interface for qobject_decref() */
                     73: #define QDECREF(obj)              \
                     74:     qobject_decref(QOBJECT(obj))
                     75: 
                     76: /* Initialize an object to default values */
                     77: #define QOBJECT_INIT(obj, qtype_type)   \
                     78:     obj->base.refcnt = 1;               \
                     79:     obj->base.type   = qtype_type
                     80: 
                     81: /**
                     82:  * qobject_incref(): Increment QObject's reference count
                     83:  */
                     84: static inline void qobject_incref(QObject *obj)
                     85: {
                     86:     if (obj)
                     87:         obj->refcnt++;
                     88: }
                     89: 
                     90: /**
                     91:  * qobject_decref(): Decrement QObject's reference count, deallocate
                     92:  * when it reaches zero
                     93:  */
                     94: static inline void qobject_decref(QObject *obj)
                     95: {
                     96:     if (obj && --obj->refcnt == 0) {
                     97:         assert(obj->type != NULL);
                     98:         assert(obj->type->destroy != NULL);
                     99:         obj->type->destroy(obj);
                    100:     }
                    101: }
                    102: 
                    103: /**
                    104:  * qobject_type(): Return the QObject's type
                    105:  */
                    106: static inline qtype_code qobject_type(const QObject *obj)
                    107: {
                    108:     assert(obj->type != NULL);
                    109:     return obj->type->code;
                    110: }
                    111: 
                    112: #endif /* QOBJECT_H */

unix.superglobalmegacorp.com