[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 31/87] object: Improve documentation of interfaces
From: |
Paolo Bonzini |
Subject: |
[PULL 31/87] object: Improve documentation of interfaces |
Date: |
Wed, 18 Dec 2019 13:01:57 +0100 |
From: Greg Kurz <address@hidden>
QOM interfaces allow a limited form of multiple inheritance, at the
condition of being stateless. That is, they cannot be instantiated
and a pointer to an interface shouldn't be dereferenceable in any way.
This is achieved by making the QOM instance type an incomplete type,
which is, as mentioned by Markus Armbruster, the closest you can get
to abstract class in C.
Incomplete types are widely used to hide implementation details, but
people usually expect to find at least one place where the type is
fully defined. The fact that it doesn't happen with QOM interfaces is
quite disturbing, especially since it isn't documented anywhere as
recently discussed in this thread:
https://lists.gnu.org/archive/html/qemu-devel/2019-12/msg01579.html
Amend the documentation in the object.h header file to provide more
details about why and how to implement QOM interfaces using incomplete
types.
Signed-off-by: Greg Kurz <address@hidden>
Reviewed-by: Marc-André Lureau <address@hidden>
Signed-off-by: Paolo Bonzini <address@hidden>
---
include/qom/object.h | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/include/qom/object.h b/include/qom/object.h
index f9ad692..bd68d19 100644
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -200,8 +200,14 @@ typedef struct InterfaceInfo InterfaceInfo;
*
* 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 #
*
--
1.8.3.1
- [PULL 09/87] migration-test: Move -incomming handling to common commandline, (continued)
- [PULL 09/87] migration-test: Move -incomming handling to common commandline, Paolo Bonzini, 2019/12/18
- [PULL 14/87] tcg: move qemu_tcg_configure to accel/tcg/tcg-all.c, Paolo Bonzini, 2019/12/18
- [PULL 15/87] vl: extract accelerator option processing to a separate function, Paolo Bonzini, 2019/12/18
- [PULL 13/87] vl: move icount configuration earlier, Paolo Bonzini, 2019/12/18
- [PULL 12/87] memory: do not look at current_machine->accel, Paolo Bonzini, 2019/12/18
- [PULL 11/87] migration-test: Use a struct for test_migrate_start parameters, Paolo Bonzini, 2019/12/18
- [PULL 16/87] vl: merge -accel processing into configure_accelerators, Paolo Bonzini, 2019/12/18
- [PULL 22/87] qom: add object_new_with_class, Paolo Bonzini, 2019/12/18
- [PULL 23/87] accel: pass object to accel_init_machine, Paolo Bonzini, 2019/12/18
- [PULL 25/87] tcg: add "-accel tcg,tb-size" and deprecate "-tb-size", Paolo Bonzini, 2019/12/18
- [PULL 31/87] object: Improve documentation of interfaces,
Paolo Bonzini <=
- [PULL 32/87] build-sys: build vhost-user-gpu only if CONFIG_TOOLS, Paolo Bonzini, 2019/12/18
- [PULL 26/87] xen: convert "-machine igd-passthru" to an accelerator property, Paolo Bonzini, 2019/12/18
- [PULL 18/87] vl: introduce object_parse_property_opt, Paolo Bonzini, 2019/12/18
- [PULL 10/87] migration-test: Rename cmd_src/dst to arch_source/arch_target, Paolo Bonzini, 2019/12/18
- [PULL 17/87] accel: compile accel/accel.c just once, Paolo Bonzini, 2019/12/18
- [PULL 19/87] vl: configure accelerators from -accel options, Paolo Bonzini, 2019/12/18
- [PULL 28/87] kvm: introduce kvm_kernel_irqchip_* functions, Paolo Bonzini, 2019/12/18
- [PULL 33/87] build-sys: do not include Windows SLIRP dependencies in $LIBS, Paolo Bonzini, 2019/12/18
- [PULL 34/87] migration: fix maybe-uninitialized warning, Paolo Bonzini, 2019/12/18
- [PULL 21/87] qom: introduce object_register_sugar_prop, Paolo Bonzini, 2019/12/18