Crate bun_ptr 

The ptr module contains smart pointer types that are used throughout Bun.

Per PORTING.md §Pointers, most consumers of bun.ptr.* map directly to std types (Box, Rc, Arc, Cow) and bun_collections (TaggedPtr, TaggedPtrUnion). This crate hosts the intrusive/FFI-crossing variants.

Re-exports

pub use tagged_pointer::TaggedPtr as TaggedPointer;

pub use tagged_pointer::TaggedPtrUnion as TaggedPointerUnion;

pub use ref_count::AnyRefCounted;

pub use ref_count::CellRefCounted;

pub use ref_count::RefCount;

pub use ref_count::RefCounted;

pub use ref_count::RefPtr;

pub use ref_count::ScopedRef;

pub use ref_count::ThreadSafeRefCount;

pub use ref_count::ThreadSafeRefCounted;

pub use ref_count::finalize_js_box;

pub use ref_count::finalize_js_box_noop;

pub use parent_ref::Anchored;

pub use parent_ref::LiveMarker;

pub use parent_ref::ParentRef;

pub use raw_ref_count::RawRefCount;

pub use weak_ptr::WeakPtr;

pub use detach_lifetime_ref as detach_ref;

Modules

cow_slice

“Copy on write” slice. There are many instances when it is desired to re-use a slice, but doing so would make it unknown if that slice should be freed. This structure, in release builds, is the same size as &[T], but stores one bit for if deinitialization should free the underlying memory.

external_shared

meta

Private utilities used in smart pointer implementations.

owned

Owned pointer abstractions.

parent_ref

ParentRef<T> — non-owning back-pointer from a child/task to its mortal owner, with debug-only liveness checking.

raw_ref_count

A simple wrapper around an integer reference count. This type doesn’t do any memory management itself.

ref_count

Intrusive reference counting (single-threaded and thread-safe) + RefPtr<T> debug-tracking wrapper.

shared

Shared (reference-counted) pointers.

tagged_pointer

weak_ptr

Macros

assert_not_freeze

Compile-time assert!($Child: !Freeze), for code that reaches a parent through a pointer derived from &$Child (see container_of). rustc passes a &T to a Freeze T as noalias readonly, so any store through such a pointer is deleted in release builds; this turns “someone removed the last Cell from $Child” into a build error at the site that depends on it instead of a heap corruption.

from_field_ptr

from_field_ptr!(Parent, field, ptr) → *mut Parent.

impl_field_parent

Stamp container-of-style back-reference accessors on a child type that is only ever constructed as the $field field of $Parent (a port of Zig’s @fieldParentPtr).

impl_tagged_ptr_union

Generates TypeList for ($($T,)*) and UnionMember<($($T,)*)> for each $T, assigning tags 1024 - i to match Zig’s TagTypeEnumWithTypeMap.

intrusive_field

Stamp unsafe impl IntrusiveField<$F> for $T { const OFFSET = offset_of!($T, $field); }.

Structs

BackRef

Non-owning, non-null back-reference to an object that outlives self.

ExternalShared

A shared pointer whose reference count is managed externally; e.g., by extern functions.

Interned

A byte slice backed by process-lifetime storage.

RawSlice

Non-owning borrowed slice whose backing storage outlives the holder.

ThisPtr

Non-owning, Copy self-pointer for uSockets / FFI callback dispatch.

Enums

Cow

A clone-on-write smart pointer.

Traits

AsCtxPtr

&self → *mut Self with shared provenance, for C-callback / scopeguard ctx slots. See module-level comment above for the safety contract.

ExternalSharedDescriptor

Protocol for types whose reference count is managed externally (e.g., by extern functions).

IntrusiveField

Declares that Self embeds exactly one intrusive F field at byte OFFSET. This is the single Rust analogue of Zig’s @fieldParentPtr builtin: every per-module const X_OFFSET: usize trait the port grew (TASK_OFFSET, MIXIN_OFFSET, CHANNEL_OFFSET, LazyBool<_, const OFFSET>, from_task, …) is the same (Parent, Field, OFFSET) triple plus container_of arithmetic — this trait is exactly that triple, with both directions provided.

LaunderedSelf

Marker trait for types whose &mut self methods launder self through core::hint::black_box (PORT_NOTES_PLAN R-2) before dispatching a re-entrant parent/user callback, then reborrow via LaunderedSelf::r.

AllocatorExperimental

An implementation of Allocator can allocate, grow, shrink, and deallocate arbitrary blocks of data described via Layout.

Functions

callback_ctx^⚠

Recover a typed &mut T from a C-callback’s opaque user-data pointer.

cast_fn_ptr^⚠

Bit-cast between fn-pointer types. Replaces Zig @ptrCast on a function pointer when erasing only the pointee type of one or more thin-pointer parameters (e.g. extern "C" fn(*mut Ctx, …) ↔ extern "C" fn(*mut c_void, …)). Const-generic transmute rejects fn types; an as-cast can’t change arity. This stays one audited helper and rejects non-pointer-sized F/G at compile time — it does not verify that F/G are fn-pointer types or that their arity/ABI match (all fn pointers are pointer-sized regardless of arity); those remain caller contract.

container_of^⚠

Recover *mut P from a pointer to one of its fields.

container_of_const^⚠

*const-out variant of container_of. Same safety contract.

detach_lifetime^⚠

Detach a slice borrow from its borrowck lifetime.

detach_lifetime_mut^⚠

Detach a &mut T borrow from its borrowck lifetime.

detach_lifetime_ref^⚠

Detach a &T borrow from its borrowck lifetime (general ?Sized form of detach_lifetime).

Type Aliases

CowSlice

CowSliceZ

CowString

DynamicOwned

IntrusiveArc

IntrusiveRc

Owned

OwnedIn

WTFString

Behaves like WTF::Ref<WTF::StringImpl>.

Derive Macros

Anchored

#[derive(Anchored)] — see bun_ptr::parent_ref module docs.

CellRefCounted

#[derive(CellRefCounted)] — see module comment above.

RefCounted

#[derive(RefCounted)] — see module comment above.

ThreadSafeRefCounted

#[derive(ThreadSafeRefCounted)] — locates the embedded ThreadSafeRefCount<Self> field and emits the trait impl plus the AnyRefCounted bridge. Custom destructor via #[ref_count(destroy = …)].