Re: [PATCH 01/12] rust: qom: add reference counting functionality

[Zhao Liu]

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 <pbonzini@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 <pbonzini@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.liu@intel.com>