shared¶
shared
(along with owned
) manage the
deallocation of a class instance. shared
is meant to be used when many
different references will exist to the object at the same time and these
references need to keep the object alive.
Please see also the language spec section Class Lifetime and Borrows.
Using shared¶
To use shared
, allocate a class instance following this
pattern:
var mySharedObject = new shared MyClass(...));
When mySharedObject
and any copies of it go out of scope, the class
instance it refers to will be deleted.
Copy initializing or assigning from mySharedObject will make other variables refer to the same class instance. The class instance will be deleted after all of these references go out of scope.
var globalSharedObject:shared MyClass;
proc makeGlobalSharedObject() {
var mySharedObject = new shared MyClass(...);
globalSharedObject = mySharedObject;
// the reference count is decremented when mySharedObject
// goes out of scope. Since it's not zero after decrementing, the
// MyClass instance is not deleted until globalSharedObject
// goes out of scope.
}
Borrowing from shared¶
The shared.borrow
method returns the pointer managed by the
shared
. This pointer is only valid as long as the shared
is
storing that pointer. The compiler includes some checking for errors in this
case. In these ways, shared
is similar to
owned
.
See Borrowing from owned for more details and examples.
Coercions for shared¶
As with owned
, shared
supports
coercions to the class type as well as
coercions from a shared(T)
to shared(U)
where T
is a
subclass of U
.
See Coercions for owned for more details and examples.
shared Default Intent¶
The default intent for shared
types is const ref
.
-
record
shared
¶ shared
manages the deletion of a class instance in a way that supports multiple owners of the class instance.This is currently implemented with task-safe reference counting.
-
proc
init
(in take: owned) Initialize a
shared
taking a pointer from aowned
.This
shared
will take over the deletion of the class instance. It is an error to directly delete the class instance while it is managed byshared
.Arguments: take – the owned value to take ownership from
-
proc
init=
(const ref src: shared)¶ Copy-initializer. Creates a new
shared
that refers to the same class instance as src. These will share responsibility for managing the instance.
-
proc type
create
(in take: owned)¶ Changes the memory management strategy of the argument from owned to shared, taking over the ownership of the argument. The result type preserves nilability of the argument type. If the argument is non-nilable, it must be recognized by the compiler as an expiring value.
-
proc type
create
(in src: shared) Creates a new shared class reference to the argument. The result has the same type as the argument.
-
proc type
create
(p: unmanaged) Starts managing the argument class instance p using the shared memory management strategy. The result type preserves nilability of the argument type.
It is an error to directly delete the class instance after passing it to shared.create().
-
proc
deinit
()¶ The deinitializer for
shared
will destroy the class instance once there are no longer any copies of thisshared
that refer to it.
-
proc ref retain(newPtr: unmanaged)
Change the instance managed by this class to newPtr. If this record was the last
shared
managing a non-nil instance, that instance will be deleted.
-
proc ref clear()
Empty this
shared
so that it stores nil. Deletes the managed object if thisshared
is the lastshared
managing that object. Does not return a value.Equivalent to
shared.retain(nil)
.
-
proc
borrow
()¶ Return the object managed by this
shared
without impacting its lifetime at all. It is an error to use the value returned by this function after the lastshared
goes out of scope or deletes the contained class instance for another reason, including calls to =, orshared.retain
when this is the lastshared
referring to the instance. In some cases such errors are caught at compile-time.
-
proc
-
proc
=
(ref lhs: shared, rhs: shared)¶ Assign one
shared
to another. Deletes the object managed bylhs
if there are no othershared
referring to it. On return,lhs
will refer to the same object asrhs
.