On Fri, Feb 07, 2025 at 11:16:12AM +0100, Paolo Bonzini wrote:
> Date: Fri, 7 Feb 2025 11:16:12 +0100
> From: Paolo Bonzini <pbonz...@redhat.com>
> Subject: [PATCH 01/12] rust: qom: add reference counting functionality
> X-Mailer: git-send-email 2.48.1
>
> Add a smart pointer that allows to add and remove references from
> QOM objects. It's important to note that while all QOM objects have a
> reference count, in practice not all of them have their lifetime guarded
> by it. Embedded objects, specifically, are confined to the lifetime of
> the owner.
>
> When writing Rust bindings this is important, because embedded objects are
> *never* used through the "Owned<>" smart pointer that is introduced here.
>
> Signed-off-by: Paolo Bonzini <pbonz...@redhat.com>
> ---
> rust/qemu-api/src/qom.rs | 158 ++++++++++++++++++++++++++++++++++-
> rust/qemu-api/src/vmstate.rs | 6 +-
> rust/qemu-api/tests/tests.rs | 10 +++
> 3 files changed, 172 insertions(+), 2 deletions(-)
>
> diff --git a/rust/qemu-api/src/qom.rs b/rust/qemu-api/src/qom.rs
> index f50ee371aac..4a2e84c9aed 100644
> --- a/rust/qemu-api/src/qom.rs
> +++ b/rust/qemu-api/src/qom.rs
> @@ -56,6 +56,7 @@
> use std::{
> ffi::CStr,
> fmt,
> + mem::ManuallyDrop,
> ops::{Deref, DerefMut},
> os::raw::c_void,
> ptr::NonNull,
> @@ -63,7 +64,13 @@
>
> pub use bindings::{Object, ObjectClass};
>
> -use crate::bindings::{self, object_dynamic_cast, object_get_class,
> object_get_typename, TypeInfo};
> +use crate::{
> + bindings::{
> + self, object_dynamic_cast, object_get_class, object_get_typename,
> object_ref, object_unref,
> + TypeInfo,
> + },
> + cell::bql_locked,
> +};
>
> /// Marker trait: `Self` can be statically upcasted to `P` (i.e. `P` is a
> direct
> /// or indirect parent of `Self`).
> @@ -610,6 +617,148 @@ unsafe impl ObjectType for Object {
> unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_OBJECT)
> };
> }
>
> +/// A reference-counted pointer to a QOM object.
> +///
> +/// `Owned<T>` wraps `T` with automatic reference counting. It increases the
> +/// reference count when created via [`Owned::from`] or cloned, and decreases
> +/// it when dropped. This ensures that the reference count remains elevated
> +/// as long as any `Owned<T>` references to it exist.
> +///
> +/// `Owned<T>` can be used for two reasons:
> +/// * because the lifetime of the QOM object is unknown and someone else
> could
> +/// take a reference (similar to `Arc<T>`, for example): in this case, the
> +/// object can escape and outlive the Rust struct that contains the
> `Owned<T>`
> +/// field;
> +///
> +/// * to ensure that the object stays alive until after `Drop::drop` is
> called
> +/// on the Rust struct: in this case, the object will always die together
> with
> +/// the Rust struct that contains the `Owned<T>` field.
> +///
> +/// Child properties are an example of the second case: in C, an object that
> +/// is created with `object_initialize_child` will die *before*
> +/// `instance_finalize` is called, whereas Rust expects the struct to have
> valid
> +/// contents when `Drop::drop` is called. Therefore Rust structs that have
> +/// child properties need to keep a reference to the child object. Right now
> +/// this can be done with `Owned<T>`; in the future one might have a separate
> +/// `Child<'parent, T>` smart pointer that keeps a reference to a `T`, like
> +/// `Owned`, but does not allow cloning.
> +///
> +/// Note that dropping an `Owned<T>` requires the big QEMU lock to be taken.
Nice doc.
LGTM,
Reviewed-by: Zhao Liu <zhao1....@intel.com>
