Annotation of qemu/qobject.h, revision 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