Struct gdnative_core::object::Instance

pub struct Instance<T: NativeClass, Own: Ownership = Shared> { /* private fields */ }

A persistent reference to a GodotObject with a rust NativeClass attached.

Instances can be worked on directly using map and map_mut if the base object is reference-counted. Otherwise, use assume_safe to obtain a temporary TInstance.

See the type-level documentation on Ref for more information on typed thread accesses.

Implementations

impl<T: NativeClass> Instance<T, Unique>

pub fn new() -> Selfwhere
    T::Base: Instanciable,

Creates a T::Base with the script T attached. Both T::Base and T must have zero argument constructors.

If T::Base is manually-managed, then the resulting Instance must be passed to the engine or manually freed with Instance::free. Otherwise, the base object will be leaked.

Must be called after the library is initialized.

pub fn emplace(script: T) -> Selfwhere
    T::Base: Instanciable,

Creates a T::Base with a given instance of the script T attached. T::Base must have a zero-argument constructor.

This may be used to create instances of scripts that do not have zero-argument constructors:

// This type does not have a zero-argument constructor. As a result, `Instance::new`
// will panic and `Foo.new` from GDScript will result in errors when the object is used.
#[derive(NativeScript)]
#[inherit(Reference)]
#[no_constructor]
struct MyIntVector(i64, i64);

#[methods]
impl MyIntVector {
    // - snip -
}

// With `Instance::emplace`, however, we can expose "constructors" from a factory
// auto-load for our script type.
#[derive(NativeScript)]
#[inherit(Node)]
#[user_data(Aether<Self>)]
struct MyIntVectorFactory;

#[methods]
impl MyIntVectorFactory {
    #[export]
    fn make(&self, _owner: &Node, x: i64, y: i64) -> Instance<MyIntVector, Unique> {
        Instance::emplace(MyIntVector(x, y))
    }
}

If T::Base is manually-managed, then the resulting Instance must be passed to the engine or manually freed with Instance::free. Otherwise, the base object will be leaked.

Must be called after the library is initialized.

impl<T: NativeClass, Own: Ownership> Instance<T, Own>

pub fn into_base(self) -> Ref<T::Base, Own>

Returns the base object, dropping the script wrapper.

pub fn into_script(self) -> T::UserData

Returns the script wrapper.

pub fn decouple(self) -> (Ref<T::Base, Own>, T::UserData)

Returns the base object and the script wrapper.

pub fn base(&self) -> &Ref<T::Base, Own>

Returns a reference to the base object.

pub fn script(&self) -> &T::UserData

Returns a reference to the script wrapper.

impl<T: NativeClass, Own: Ownership> Instance<T, Own>where
    RefImplBound: SafeAsRaw<<T::Base as GodotObject>::Memory, Own>,

pub fn try_from_base(
    owner: Ref<T::Base, Own>
) -> Result<Self, Ref<T::Base, Own>>

Try to downcast Ref<T::Base, Own> to Instance<T>, without changing the reference count if reference-counted.

Errors

Returns the original Ref if the cast failed.

pub fn from_base(owner: Ref<T::Base, Own>) -> Option<Self>

Try to downcast Ref<T::Base, Own> to Instance<T>, without changing the reference count if reference-counted. Shorthand for Self::try_from_base().ok().

impl<T: NativeClass, Own: Ownership> Instance<T, Own>where
    RefImplBound: SafeDeref<<T::Base as GodotObject>::Memory, Own>,

pub fn map<F, U>(&self, op: F) -> Result<U, <T::UserData as Map>::Err>where
    T::UserData: Map,
    F: FnOnce(&T, TRef<'_, T::Base, Own>) -> U,

Calls a function with a NativeClass instance and its owner, and returns its return value. Can be used on reference counted types for multiple times.

pub fn map_mut<F, U>(&self, op: F) -> Result<U, <T::UserData as MapMut>::Err>where
    T::UserData: MapMut,
    F: FnOnce(&mut T, TRef<'_, T::Base, Own>) -> U,

Calls a function with a NativeClass instance and its owner, and returns its return value. Can be used on reference counted types for multiple times.

pub fn map_owned<F, U>(&self, op: F) -> Result<U, <T::UserData as MapOwned>::Err>where
    T::UserData: MapOwned,
    F: FnOnce(T, TRef<'_, T::Base, Own>) -> U,

Calls a function with a NativeClass instance and its owner, and returns its return value. Can be used on reference counted types for multiple times.

impl<T: NativeClass> Instance<T, Shared>

Methods for instances with manually-managed base classes.

pub unsafe fn assume_safe<'a, 'r>(&'r self) -> TInstance<'a, T, Shared>where
    AssumeSafeLifetime<'a, 'r>: LifetimeConstraint<<T::Base as GodotObject>::Memory>,

Assume that self is safe to use.

This is not guaranteed to be a no-op at runtime.

Safety

It’s safe to call assume_safe only if the constraints of Ref::assume_safe are satisfied for the base object.

impl<T: NativeClass> Instance<T, Shared>where
    T::Base: GodotObject<Memory = ManuallyManaged>,

pub unsafe fn is_instance_sane(&self) -> bool

Returns true if the pointer currently points to a valid object of the correct type. This does NOT guarantee that it’s safe to use this pointer.

Safety

This thread must have exclusive access to the object during the call.

impl<T: NativeClass> Instance<T, Unique>where
    T::Base: GodotObject<Memory = ManuallyManaged>,

pub fn free(self)

Frees the base object and user-data wrapper.

Same as self.into_base().free().

impl<T: NativeClass> Instance<T, Unique>where
    T::Base: GodotObject<Memory = ManuallyManaged> + QueueFree,

pub fn queue_free(self)

Queues the base object and user-data wrapper for deallocation in the near future. This should be preferred to free for Nodes.

Same as self.into_base().queue_free().

impl<T: NativeClass> Instance<T, Unique>

pub fn into_shared(self) -> Instance<T, Shared>

Coverts into a Shared instance.

impl<T: NativeClass> Instance<T, Unique>where
    T::Base: GodotObject<Memory = RefCounted>,

pub fn into_thread_local(self) -> Instance<T, ThreadLocal>

Coverts into a ThreadLocal instance.

impl<T: NativeClass> Instance<T, Shared>

pub unsafe fn assume_unique(self) -> Instance<T, Unique>

Assume that self is the unique reference to the underlying base object.

This is guaranteed to be a no-op at runtime if debug_assertions is disabled. Runtime sanity checks may be added in debug builds to help catch bugs.

Safety

Calling assume_unique when self isn’t the unique reference is instant undefined behavior. This is a much stronger assumption than assume_safe and should be used with care.

impl<T: NativeClass> Instance<T, Shared>where
    T::Base: GodotObject<Memory = RefCounted>,

pub unsafe fn assume_thread_local(self) -> Instance<T, ThreadLocal>

Assume that all references to the underlying object is local to the current thread.

This is guaranteed to be a no-op at runtime.

Safety

Calling assume_thread_local when there are references on other threads is instant undefined behavior. This is a much stronger assumption than assume_safe and should be used with care.

Trait Implementations

impl<T, Own: Ownership> Clone for Instance<T, Own>where
    T: NativeClass,
    Ref<T::Base, Own>: Clone,

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + NativeClass, Own: Debug + Ownership> Debug for Instance<T, Own>where
    T::Base: Debug,
    T::UserData: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Export for Instance<T, Shared>where
    T: NativeClass,
    Instance<T, Shared>: ToVariant,

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(_hint: Option<Self::Hint>) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl<T> FromVariant for Instance<T, Shared>where
    T: NativeClass,
    T::Base: GodotObject<Memory = RefCounted>,

fn from_variant(variant: &Variant) -> Result<Self, FromVariantError>

impl<T> OwnedToVariant for Instance<T, Unique>where
    T: NativeClass,

fn owned_to_variant(self) -> Variant

impl<T, Own: Ownership> ToVariant for Instance<T, Own>where
    T: NativeClass,
    Ref<T::Base, Own>: ToVariant,

fn to_variant(&self) -> Variant

impl<'a, T, U> AsArg<U> for &'a Instance<T, Shared>where
    T: NativeClass,
    T::Base: GodotObject + SubClass<U>,
    T::UserData: Map,
    U: GodotObject,

impl<T, U, Own: Ownership> AsArg<U> for Instance<T, Own>where
    T: NativeClass,
    T::Base: GodotObject + SubClass<U>,
    T::UserData: Map,
    U: GodotObject,