WeakRefProtocol
public protocol WeakRefProtocol
A structure containing a weak reference to a GObject
.
A GWeakRef
can either be empty (i.e. point to nil
), or point to an
object for as long as at least one “strong” reference to that object
exists. Before the object’s GObjectClass.dispose
method is called,
every GWeakRef
associated with becomes empty (i.e. points to nil
).
Like GValue
, GWeakRef
can be statically allocated, stack- or
heap-allocated, or embedded in larger structures.
Unlike g_object_weak_ref()
and g_object_add_weak_pointer()
, this weak
reference is thread-safe: converting a weak pointer to a reference is
atomic with respect to invalidation of weak pointers to destroyed
objects.
If the object’s GObjectClass.dispose
method results in additional
references to the object being held (‘re-referencing’), any GWeakRefs
taken
before it was disposed will continue to point to nil
. Any GWeakRefs
taken
during disposal and after re-referencing, or after disposal has returned due
to the re-referencing, will continue to point to the object until its refcount
goes back to zero, at which point they too will be invalidated.
It is invalid to take a GWeakRef
on an object during GObjectClass.dispose
without first having or creating a strong reference to the object.
The WeakRefProtocol
protocol exposes the methods and properties of an underlying GWeakRef
instance.
The default implementation of these can be found in the protocol extension below.
For a concrete class that implements these methods and properties, see WeakRef
.
Alternatively, use WeakRefRef
as a lighweight, unowned
reference if you already have an instance you just want to use.
-
Untyped pointer to the underlying
GWeakRef
instance.Declaration
Swift
var ptr: UnsafeMutableRawPointer! { get }
-
_ptr
Default implementationTyped pointer to the underlying
GWeakRef
instance.Default Implementation
Return the stored, untyped pointer as a typed pointer to the
GWeakRef
instance.Declaration
Swift
var _ptr: UnsafeMutablePointer<GWeakRef>! { get }
-
Required Initialiser for types conforming to
WeakRefProtocol
Declaration
Swift
init(raw: UnsafeMutableRawPointer)
-
clear()
Extension methodFrees resources associated with a non-statically-allocated
GWeakRef
. After this call, theGWeakRef
is left in an undefined state.You should only call this on a
GWeakRef
that previously hadg_weak_ref_init()
called on it.Declaration
Swift
@inlinable func clear()
-
get()
Extension methodIf
weak_ref
is not empty, atomically acquire a strong reference to the object it points to, and return that reference.This function is needed because of the potential race between taking the pointer value and
g_object_ref()
on it, if the object was losing its last reference at the same time in a different thread.The caller should release the resulting reference in the usual way, by using
g_object_unref()
.Declaration
Swift
@inlinable func get() -> GLibObject.ObjectRef!
-
init_(object:
Extension method) Initialise a non-statically-allocated
GWeakRef
.This function also calls
g_weak_ref_set()
withobject
on the freshly-initialised weak reference.This function should always be matched with a call to
g_weak_ref_clear()
. It is not necessary to use this function for aGWeakRef
in static storage because it will already be properly initialised. Just useg_weak_ref_set()
directly.Declaration
Swift
@inlinable func init_(object: ObjectRef? = nil)
-
init_(object:
Extension method) Initialise a non-statically-allocated
GWeakRef
.This function also calls
g_weak_ref_set()
withobject
on the freshly-initialised weak reference.This function should always be matched with a call to
g_weak_ref_clear()
. It is not necessary to use this function for aGWeakRef
in static storage because it will already be properly initialised. Just useg_weak_ref_set()
directly.Declaration
Swift
@inlinable func init_<ObjectT>(object: ObjectT?) where ObjectT : ObjectProtocol
-
set(object:
Extension method) Change the object to which
weak_ref
points, or set it tonil
.You must own a strong reference on
object
while calling this function.Declaration
Swift
@inlinable func set(object: ObjectRef? = nil)
-
set(object:
Extension method) Change the object to which
weak_ref
points, or set it tonil
.You must own a strong reference on
object
while calling this function.Declaration
Swift
@inlinable func set<ObjectT>(object: ObjectT?) where ObjectT : ObjectProtocol