Mojo struct

ArcPointer

struct ArcPointer[T: Movable & ImplicitlyDestructible]

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 std.memory import ArcPointer
var p = ArcPointer(4)
var p2 = p
p2[]=3
print(3 == p[])

Parameters

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

Implemented traits

AnyType, Copyable, Equatable, Hashable, Identifiable, ImplicitlyCopyable, ImplicitlyDestructible, Movable, RegisterPassable, Writable

Methods

__init__

__init__(var value: T) -> Self

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__(*, unsafe_from_raw_pointer: UnsafePointer[T, MutExternalOrigin]) -> Self

Constructs an ArcPointer from a raw pointer.

Safety

The unsafe_from_raw_pointer argument must have been previously returned by a call to ArcPointer.steal_data. Any other pointer may result in undefined behaviour.

Example

from std.memory import ArcPointer

var initial_arc = ArcPointer[Int](42)
var raw_ptr = initial_arc^.steal_data()

# The following will ensure the data is properly destroyed and deallocated.
var restored_arc = ArcPointer(unsafe_from_raw_pointer=raw_ptr)

Args:

• ​unsafe_from_raw_pointer (UnsafePointer): A raw pointer previously returned from ArcPointer.steal_data.

__init__(*, copy: Self) -> Self

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

Args:

• ​copy (Self): The existing reference.

__del__

__del__(deinit 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: ImmutOrigin](ref[T] self) -> ref[T] T

Returns a mutable reference to the managed value.

Parameters:

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

Returns:

ref: A reference to the managed value.

__eq__

__eq__(self, rhs: Self) -> Bool where conforms_to(T, AnyType & ImplicitlyDestructible & Equatable)

Returns True if the two ArcPointer instances hold equal values.

Delegates to the underlying value's __eq__ method, so two ArcPointer instances holding equal values compare equal even if they are separate allocations. This is consistent with __hash__.

Args:

• ​rhs (Self): The other ArcPointer.

Returns:

Bool: True if the managed values are equal, False otherwise.

__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:

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

unsafe_ptr

unsafe_ptr[mut: Bool, origin: Origin[mut=mut], //](ref[mut] self) -> UnsafePointer[T, origin]

Retrieves a pointer to the underlying memory.

Parameters:

• ​mut (Bool): Whether the pointer is mutable.
• ​origin (Origin): The origin of the pointer.

Returns:

UnsafePointer: An UnsafePointer to the pointee.

count

count(self) -> UInt64

Count the amount of current references.

Returns:

UInt64: The current amount of references to the pointee.

steal_data

steal_data(deinit self) -> UnsafePointer[T, MutExternalOrigin]

Consume this ArcPointer, returning a raw pointer to the underlying data.

Safety

To avoid leaking memory, this pointer must be converted back to an ArcPointer using ArcPointer(unsafe_from_raw_pointer=ptr). The returned pointer is not guaranteed to point to the beginning of the backing allocation, meaning calling UnsafePointer.free may result in undefined behavior.

Returns:

UnsafePointer: An UnsafePointer to the underlying T value.

__hash__

__hash__[H: Hasher](self, mut hasher: H) where conforms_to(T, AnyType & Hashable)

Hash the managed value.

Delegates to the underlying value's __hash__ method, so two ArcPointer instances holding equal values produce the same hash. This is consistent with __eq__.

Parameters:

• ​H (Hasher): The hasher type.

Args:

• ​hasher (H): The hasher instance to update.

write_to

write_to(self, mut writer: T) where conforms_to(T, AnyType & ImplicitlyDestructible & Writable)

Formats this pointer's value to the provided Writer.

Constraints:

T must conform to Writable.

Args:

• ​writer (T): The object to write to.

write_repr_to

write_repr_to(self, mut writer: T) where conforms_to(T, AnyType & ImplicitlyDestructible & Writable)

Write the string representation of the ArcPointer.

Constraints:

T must conform to Writable.

Args:

• ​writer (T): The object to write to.

Was this page helpful?

Thank you! We'll create more content like this.

Thank you for helping us improve!

😔 What went wrong?

Some code doesn’t work

It includes inaccurate information

It's missing information I need

It was difficult to understand

Other

Submit