Skip to main content

/

Docs

Nightly

v24.6

Log in

Mojo struct

ArcPointer

@register_passable struct ArcPointer[T: Movable]

Atomic reference-counted pointer.

This smart pointer owns an instance of T indirectly managed on the heap. This pointer is copyable, including across threads, maintaining a reference count to the underlying data.

When you initialize an ArcPointer with a value, it allocates memory and moves the value into the allocated memory. Copying an instance of an ArcPointer increments the reference count. Destroying an instance decrements the reference count. When the reference count reaches zero, ArcPointer destroys the value and frees its memory.

This pointer itself is thread-safe using atomic accesses to reference count the underlying data, but references returned to the underlying data are not thread-safe.

Subscripting an ArcPointer (ptr[]) returns a mutable reference to the stored value. This is the only safe way to access the stored value. Other methods, such as using the unsafe_ptr() method to retrieve an unsafe pointer to the stored value, or accessing the private fields of an ArcPointer, are unsafe and may result in memory errors.

For a comparison with other pointer types, see Intro to pointers in the Mojo Manual.

Examples:

from memory import ArcPointer
var p = ArcPointer(4)
var p2 = p
p2[]=3
print(3 == p[])
from memory import ArcPointer
var p = ArcPointer(4)
var p2 = p
p2[]=3
print(3 == p[])

Parameters​

  • ​T (Movable): The type of the stored value.

Implemented traits​

AnyType, CollectionElement, CollectionElementNew, Copyable, ExplicitlyCopyable, Identifiable, Movable, UnknownDestructibility

Methods​

__init__​

__init__(out self, owned value: T)

Construct a new thread-safe, reference-counted smart pointer, and move the value into heap memory managed by the new pointer.

Args:

  • ​value (T): The value to manage.

__init__(out self, *, other: Self)

Copy the object.

Args:

  • ​other (Self): The value to copy.

__copyinit__​

__copyinit__(out self, existing: Self)

Copy an existing reference. Increment the refcount to the object.

Args:

  • ​existing (Self): The existing reference.

__del__​

__del__(owned self)

Delete the smart pointer.

Decrement the reference count for the stored value. If there are no more references, delete the object and free its memory.

__getitem__​

__getitem__[self_life: ImmutableOrigin](ref [self_life] self) -> ref [self_life] T

Returns a mutable reference to the managed value.

Parameters:

  • ​self_life (ImmutableOrigin): The origin of self.

Returns:

A reference to the managed value.

__is__​

__is__(self, rhs: Self) -> Bool

Returns True if the two ArcPointer instances point at the same object.

Args:

  • ​rhs (Self): The other ArcPointer.

Returns:

True if the two ArcPointers instances point at the same object and False otherwise.

__isnot__​

__isnot__(self, rhs: Self) -> Bool

Returns True if the two ArcPointer instances point at different objects.

Args:

  • ​rhs (Self): The other ArcPointer.

Returns:

True if the two ArcPointer instances point at different objects and False otherwise.

unsafe_ptr​

unsafe_ptr(self) -> UnsafePointer[T]

Retrieves a pointer to the underlying memory.

Returns:

The UnsafePointer to the pointee.

count​

count(self) -> SIMD[uint64, 1]

Count the amount of current references.

Returns:

The current amount of references to the pointee.