LXR qemu/include/qapi/qmp/qobject.h

   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 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 "qapi-types.h"
  36
  37struct QObject {
  38    QType type;
  39    size_t refcnt;
  40};
  41
  42/* Get the 'base' part of an object */
  43#define QOBJECT(obj) (&(obj)->base)
  44
  45/* High-level interface for qobject_incref() */
  46#define QINCREF(obj)      \
  47    qobject_incref(QOBJECT(obj))
  48
  49/* High-level interface for qobject_decref() */
  50#define QDECREF(obj)              \
  51    qobject_decref(obj ? QOBJECT(obj) : NULL)
  52
  53/* Initialize an object to default values */
  54static inline void qobject_init(QObject *obj, QType type)
  55{
  56    assert(QTYPE_NONE < type && type < QTYPE__MAX);
  57    obj->refcnt = 1;
  58    obj->type = type;
  59}
  60
  61/**
  62 * qobject_incref(): Increment QObject's reference count
  63 */
  64static inline void qobject_incref(QObject *obj)
  65{
  66    if (obj)
  67        obj->refcnt++;
  68}
  69
  70/**
  71 * qobject_destroy(): Free resources used by the object
  72 */
  73void qobject_destroy(QObject *obj);
  74
  75/**
  76 * qobject_decref(): Decrement QObject's reference count, deallocate
  77 * when it reaches zero
  78 */
  79static inline void qobject_decref(QObject *obj)
  80{
  81    assert(!obj || obj->refcnt);
  82    if (obj && --obj->refcnt == 0) {
  83        qobject_destroy(obj);
  84    }
  85}
  86
  87/**
  88 * qobject_type(): Return the QObject's type
  89 */
  90static inline QType qobject_type(const QObject *obj)
  91{
  92    assert(QTYPE_NONE < obj->type && obj->type < QTYPE__MAX);
  93    return obj->type;
  94}
  95
  96extern QObject qnull_;
  97
  98static inline QObject *qnull(void)
  99{
 100    qobject_incref(&qnull_);
 101    return &qnull_;
 102}
 103
 104#endif /* QOBJECT_H */
 105