#ifndef QEMU_OBJECT_H
#define QEMU_OBJECT_H
-#include "qapi-types.h"
-#include "qemu/queue.h"
+#include "qapi/qapi-builtin-types.h"
+#include "qemu/module.h"
struct TypeImpl;
typedef struct TypeImpl *Type;
-typedef struct ObjectClass ObjectClass;
typedef struct Object Object;
typedef struct TypeInfo TypeInfo;
* #TypeInfo describes information about the type including what it inherits
* from, the instance and class size, and constructor/destructor hooks.
*
+ * Alternatively several static types could be registered using helper macro
+ * DEFINE_TYPES()
+ *
+ * <example>
+ * <programlisting>
+ * static const TypeInfo device_types_info[] = {
+ * {
+ * .name = TYPE_MY_DEVICE_A,
+ * .parent = TYPE_DEVICE,
+ * .instance_size = sizeof(MyDeviceA),
+ * },
+ * {
+ * .name = TYPE_MY_DEVICE_B,
+ * .parent = TYPE_DEVICE,
+ * .instance_size = sizeof(MyDeviceB),
+ * },
+ * };
+ *
+ * DEFINE_TYPES(device_types_info)
+ * </programlisting>
+ * </example>
+ *
* Every type has an #ObjectClass associated with it. #ObjectClass derivatives
* are instantiated dynamically but there is only ever one instance for any
* given type. The #ObjectClass typically holds a table of function pointers
*
* Interfaces allow a limited form of multiple inheritance. Instances are
* similar to normal types except for the fact that are only defined by
- * their classes and never carry any state. You can dynamically cast an object
- * to one of its #Interface types and vice versa.
+ * their classes and never carry any state. As a consequence, a pointer to
+ * an interface instance should always be of incomplete type in order to be
+ * sure it cannot be dereferenced. That is, you should define the
+ * 'typedef struct SomethingIf SomethingIf' so that you can pass around
+ * 'SomethingIf *si' arguments, but not define a 'struct SomethingIf { ... }'.
+ * The only things you can validly do with a 'SomethingIf *' are to pass it as
+ * an argument to a method on its corresponding SomethingIfClass, or to
+ * dynamically cast it to an object that implements the interface.
*
* # Methods #
*
* parent class initialization has occurred, but before the class itself
* is initialized. This is the function to use to undo the effects of
* memcpy from the parent class to the descendants.
- * @class_finalize: This function is called during class destruction and is
- * meant to release and dynamic parameters allocated by @class_init.
- * @class_data: Data to pass to the @class_init, @class_base_init and
- * @class_finalize functions. This can be useful when building dynamic
+ * @class_data: Data to pass to the @class_init,
+ * @class_base_init. This can be useful when building dynamic
* classes.
* @interfaces: The list of interfaces associated with this type. This
* should point to a static array that's terminated with a zero filled
void (*class_init)(ObjectClass *klass, void *data);
void (*class_base_init)(ObjectClass *klass, void *data);
- void (*class_finalize)(ObjectClass *klass, void *data);
void *class_data;
InterfaceInfo *interfaces;
((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \
__FILE__, __LINE__, __func__))
+/**
+ * object_new_with_class:
+ * @klass: The class to instantiate.
+ *
+ * This function will initialize a new object using heap allocated memory.
+ * The returned object has a reference count of 1, and will be freed when
+ * the last reference is dropped.
+ *
+ * Returns: The newly allocated and instantiated object.
+ */
+Object *object_new_with_class(ObjectClass *klass);
+
/**
* object_new:
* @typename: The name of the type of the object to instantiate.
Error **errp,
va_list vargs);
+void object_apply_global_props(Object *obj, const GPtrArray *props,
+ Error **errp);
+void object_set_machine_compat_props(GPtrArray *compat_props);
+void object_set_accelerator_compat_props(GPtrArray *compat_props);
+void object_register_sugar_prop(const char *driver, const char *prop, const char *value);
+void object_apply_compat_props(Object *obj);
+
/**
* object_set_props:
* @obj: the object instance to set properties on
*/
void object_initialize(void *obj, size_t size, const char *typename);
+/**
+ * object_initialize_child:
+ * @parentobj: The parent object to add a property to
+ * @propname: The name of the property
+ * @childobj: A pointer to the memory to be used for the object.
+ * @size: The maximum size available at @childobj for the object.
+ * @type: The name of the type of the object to instantiate.
+ * @errp: If an error occurs, a pointer to an area to store the error
+ * @...: list of property names and values
+ *
+ * This function will initialize an object. The memory for the object should
+ * have already been allocated. The object will then be added as child property
+ * to a parent with object_property_add_child() function. The returned object
+ * has a reference count of 1 (for the "child<...>" property from the parent),
+ * so the object will be finalized automatically when the parent gets removed.
+ *
+ * The variadic parameters are a list of pairs of (propname, propvalue)
+ * strings. The propname of %NULL indicates the end of the property list.
+ * If the object implements the user creatable interface, the object will
+ * be marked complete once all the properties have been processed.
+ */
+void object_initialize_child(Object *parentobj, const char *propname,
+ void *childobj, size_t size, const char *type,
+ Error **errp, ...) QEMU_SENTINEL;
+
+/**
+ * object_initialize_childv:
+ * @parentobj: The parent object to add a property to
+ * @propname: The name of the property
+ * @childobj: A pointer to the memory to be used for the object.
+ * @size: The maximum size available at @childobj for the object.
+ * @type: The name of the type of the object to instantiate.
+ * @errp: If an error occurs, a pointer to an area to store the error
+ * @vargs: list of property names and values
+ *
+ * See object_initialize_child() for documentation.
+ */
+void object_initialize_childv(Object *parentobj, const char *propname,
+ void *childobj, size_t size, const char *type,
+ Error **errp, va_list vargs);
+
/**
* object_dynamic_cast:
* @obj: The object to cast.
* @info and all of the strings it points to should exist for the life time
* that the type is registered.
*
- * Returns: 0 on failure, the new #Type on success.
+ * Returns: the new #Type.
*/
Type type_register_static(const TypeInfo *info);
* Unlike type_register_static(), this call does not require @info or its
* string members to continue to exist after the call returns.
*
- * Returns: 0 on failure, the new #Type on success.
+ * Returns: the new #Type.
*/
Type type_register(const TypeInfo *info);
+/**
+ * type_register_static_array:
+ * @infos: The array of the new type #TypeInfo structures.
+ * @nr_infos: number of entries in @infos
+ *
+ * @infos and all of the strings it points to should exist for the life time
+ * that the type is registered.
+ */
+void type_register_static_array(const TypeInfo *infos, int nr_infos);
+
+/**
+ * DEFINE_TYPES:
+ * @type_array: The array containing #TypeInfo structures to register
+ *
+ * @type_array should be static constant that exists for the life time
+ * that the type is registered.
+ */
+#define DEFINE_TYPES(type_array) \
+static void do_qemu_init_ ## type_array(void) \
+{ \
+ type_register_static_array(type_array, ARRAY_SIZE(type_array)); \
+} \
+type_init(do_qemu_init_ ## type_array)
+
/**
* object_class_dynamic_cast_assert:
* @klass: The #ObjectClass to attempt to cast.
GSList *object_class_get_list(const char *implements_type,
bool include_abstract);
+/**
+ * object_class_get_list_sorted:
+ * @implements_type: The type to filter for, including its derivatives.
+ * @include_abstract: Whether to include abstract classes.
+ *
+ * Returns: A singly-linked list of the classes in alphabetical
+ * case-insensitive order.
+ */
+GSList *object_class_get_list_sorted(const char *implements_type,
+ bool include_abstract);
+
/**
* object_ref:
* @obj: the object
void object_property_iter_init(ObjectPropertyIterator *iter,
Object *obj);
+/**
+ * object_class_property_iter_init:
+ * @klass: the class
+ *
+ * Initializes an iterator for traversing all properties
+ * registered against an object class and all parent classes.
+ *
+ * It is forbidden to modify the property list while iterating,
+ * whether removing or adding properties.
+ *
+ * This can be used on abstract classes as it does not create a temporary
+ * instance.
+ */
+void object_class_property_iter_init(ObjectPropertyIterator *iter,
+ ObjectClass *klass);
+
/**
* object_property_iter_next:
* @iter: the iterator instance
* @errp: returns an error if this function fails
*
* Writes an object's canonical path to a property.
+ *
+ * If the link property was created with
+ * <code>OBJ_PROP_LINK_STRONG</code> bit, the old target object is
+ * unreferenced, and a reference is added to the new target object.
+ *
*/
void object_property_set_link(Object *obj, Object *value,
const char *name, Error **errp);
*
* Returns: The final component in the object's canonical path. The canonical
* path is the path within the composition tree starting from the root.
+ * %NULL if the object doesn't have a parent (and thus a canonical path).
*/
gchar *object_get_canonical_path_component(Object *obj);
* @obj: the object to add a property to
* @name: the name of the property
* @child: the child object
- * @errp: if an error occurs, a pointer to an area to store the area
+ * @errp: if an error occurs, a pointer to an area to store the error
*
* Child properties form the composition tree. All objects need to be a child
* of another object. Objects can only be a child of one object.
typedef enum {
/* Unref the link pointer when the property is deleted */
- OBJ_PROP_LINK_UNREF_ON_RELEASE = 0x1,
+ OBJ_PROP_LINK_STRONG = 0x1,
} ObjectPropertyLinkFlags;
/**
* @child: a pointer to where the link object reference is stored
* @check: callback to veto setting or NULL if the property is read-only
* @flags: additional options for the link
- * @errp: if an error occurs, a pointer to an area to store the area
+ * @errp: if an error occurs, a pointer to an area to store the error
*
* Links establish relationships between objects. Links are unidirectional
* although two links can be combined to form a bidirectional relationship
* link property. The reference count for <code>*@child</code> is
* managed by the property from after the function returns till the
* property is deleted with object_property_del(). If the
- * <code>@flags</code> <code>OBJ_PROP_LINK_UNREF_ON_RELEASE</code> bit is set,
- * the reference count is decremented when the property is deleted.
+ * <code>@flags</code> <code>OBJ_PROP_LINK_STRONG</code> bit is set,
+ * the reference count is decremented when the property is deleted or
+ * modified.
*/
void object_property_add_link(Object *obj, const char *name,
const char *type, Object **child,
* property of type 'uint64'.
*/
void object_property_add_uint64_ptr(Object *obj, const char *name,
- const uint64_t *v, Error **Errp);
+ const uint64_t *v, Error **errp);
void object_class_property_add_uint64_ptr(ObjectClass *klass, const char *name,
- const uint64_t *v, Error **Errp);
+ const uint64_t *v, Error **errp);
/**
* object_property_add_alias:
projects / mirror_qemu.git / blobdiff