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(type t)

Default-initialize a shared.

proc init(in take: owned)

Initialize a shared taking a pointer from a owned.

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 by shared.

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 this shared 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 this shared is the last shared 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 last shared goes out of scope or deletes the contained class instance for another reason, including calls to =, or shared.retain when this is the last shared referring to the instance. In some cases such errors are caught at compile-time.

proc =(ref lhs: shared, rhs: shared)

Assign one shared to another. Deletes the object managed by lhs if there are no other shared referring to it. On return, lhs will refer to the same object as rhs.

proc =(ref lhs: shared, in rhs: owned)

Set a shared from a owned. Deletes the object managed by lhs if there are no other shared referring to it. On return, lhs will refer to the object previously managed by rhs, and rhs will refer to nil.

proc <=>(ref lhs: shared, ref rhs: shared)

Swap two shared objects.