Struct gdnative::prelude::Instance

pub struct Instance<T, Access> where
    Access: ThreadAccess,
    T: NativeClass,  { /* fields omitted */ }

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 RefInstance.

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

Implementations

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

pub fn new() -> Instance<T, Unique> where
    <T as NativeClass>::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.

impl<T, Access> Instance<T, Access> where
    Access: ThreadAccess,
    T: NativeClass, 

pub fn into_base(self) -> Ref<<T as NativeClass>::Base, Access>

Returns the base object, dropping the script wrapper.

pub fn into_script(self) -> <T as NativeClass>::UserData

Returns the script wrapper.

pub fn decouple(
    self
) -> (Ref<<T as NativeClass>::Base, Access>, <T as NativeClass>::UserData)

Returns the base object and the script wrapper.

pub fn base(&self) -> &Ref<<T as NativeClass>::Base, Access>

Returns a reference to the base object.

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

Returns a reference to the script wrapper.

impl<T, Access> Instance<T, Access> where
    Access: ThreadAccess,
    T: NativeClass,
    RefImplBound: SafeAsRaw<<<T as NativeClass>::Base as GodotObject>::RefKind, Access>, 

pub fn try_from_base(
    owner: Ref<<T as NativeClass>::Base, Access>
) -> Result<Instance<T, Access>, Ref<<T as NativeClass>::Base, Access>>

Try to downcast Ref<T::Base, Access> 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 as NativeClass>::Base, Access>
) -> Option<Instance<T, Access>>

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

impl<T, Access> Instance<T, Access> where
    Access: ThreadAccess,
    T: NativeClass,
    RefImplBound: SafeDeref<<<T as NativeClass>::Base as GodotObject>::RefKind, Access>, 

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

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 as NativeClass>::UserData as MapMut>::Err> where
    F: FnOnce(&mut T, TRef<<T as NativeClass>::Base, Access>) -> U,
    <T as NativeClass>::UserData: MapMut, 

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> Instance<T, Shared> where
    T: NativeClass, 

Methods for instances with manually-managed base classes.

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

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> Instance<T, Unique> where
    T: NativeClass,
    <T as NativeClass>::Base: GodotObject,
    <<T as NativeClass>::Base as GodotObject>::RefKind == ManuallyManaged, 

pub fn free(self)

Frees the base object and user-data wrapper.

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

impl<T> Instance<T, Unique> where
    T: NativeClass,
    <T as NativeClass>::Base: GodotObject,
    <T as NativeClass>::Base: QueueFree,
    <<T as NativeClass>::Base as GodotObject>::RefKind == ManuallyManaged, 

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> Instance<T, Unique> where
    T: NativeClass, 

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

Coverts into a Shared instance.

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

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

Coverts into a ThreadLocal instance.

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

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> Instance<T, Shared> where
    T: NativeClass,
    <T as NativeClass>::Base: GodotObject,
    <<T as NativeClass>::Base as GodotObject>::RefKind == 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, Access> Clone for Instance<T, Access> where
    Access: ThreadAccess,
    T: NativeClass,
    Ref<<T as NativeClass>::Base, Access>: Clone, 

fn clone(&self) -> Instance<T, Access>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, Access> Debug for Instance<T, Access> where
    Access: ThreadAccess + Debug,
    T: NativeClass + Debug,
    <T as NativeClass>::Base: Debug,
    <T as NativeClass>::UserData: Debug, 

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

Formats the value using the given formatter.

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

type Hint = ()

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

fn export_info(
    _hint: Option<<Instance<T, Shared> as Export>::Hint>
) -> ExportInfo

Returns ExportInfo given an optional typed hint.

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

fn from_variant(
    variant: &Variant
) -> Result<Instance<T, Shared>, FromVariantError>

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

fn owned_to_variant(self) -> Variant

impl<T, Access> ToVariant for Instance<T, Access> where
    Access: ThreadAccess,
    T: NativeClass,
    Ref<<T as NativeClass>::Base, Access>: ToVariant, 

fn to_variant(&self) -> Variant