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[])Parameters
- T (
Movable): The type of the stored value.
Implemented traits
AnyType,
Copyable,
Identifiable,
ImplicitlyCopyable,
Movable,
UnknownDestructibility
Aliases
__copyinit__is_trivial
alias __copyinit__is_trivial = False
__del__is_trivial
alias __del__is_trivial = False
__moveinit__is_trivial
alias __moveinit__is_trivial = UnsafePointer[_ArcPointerInner[T]].__moveinit__is_trivial
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]) -> 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 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 fromArcPointer.steal_data.
__copyinit__
__copyinit__(existing: Self) -> Self
Copy an existing reference. Increment the refcount to the object.
Args:
- existing (
Self): The existing reference.
__del__
__del__(var 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:
ref: 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 otherArcPointer.
Returns:
Bool: True if the two ArcPointers instances point at the same object and
False otherwise.
unsafe_ptr
unsafe_ptr(self) -> UnsafePointer[T]
Retrieves a pointer to the underlying memory.
Returns:
UnsafePointer: The 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(var self) -> UnsafePointer[T]
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.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!