Module

std::rc

Rc Module

Reference-counted shared ownership for heap-allocated values.

Rc<T> provides shared ownership of a value of type T allocated on the heap. Cloning an Rc increments the reference count; dropping one decrements it. When the last strong reference is released, the payload’s destructor runs. The allocation is freed when both strong and weak counts reach zero.

Weak<T> is a non-owning observer. It keeps the allocation header alive so upgrade() can check whether the value still exists, but does not prevent the payload from being destroyed.

Both types are move-by-default. Use .clone() to share.

Example

import Rc, Weak from "std::rc";
import Option from "std::option";

function main(): i32 {
  let a: Rc<i32> = Rc::new<i32>(42);
  let b: Rc<i32> = a.clone();
  let w: Weak<i32> = a.downgrade();
  let upgraded: Option<Rc<i32>> = w.upgrade(); // SOME while a or b is alive
  return 0;
}

namespace __rc_ffi

Functions

function ignis_rc_alloc(payload_size: u64, payload_align: u64, drop_fn: fn(*mut u8) -> void): *mut void

Allocates an Rc control block and payload storage.

function ignis_rc_count(handle: *mut void): u32

Returns the current strong reference count.

function ignis_rc_downgrade(handle: *mut void): void

Converts a strong handle into an additional weak reference.

function ignis_rc_get(handle: *mut void): *mut void

Returns the payload pointer for an Rc/Weak runtime handle.

function ignis_rc_release(handle: *mut void): void

Decrements the strong reference count and may drop the payload.

function ignis_rc_retain(handle: *mut void): void

Increments the strong reference count.

function ignis_rc_upgrade(handle: *mut void): *mut void

Attempts to upgrade a weak handle to a strong handle.

function ignis_weak_count(handle: *mut void): u32

Returns the current weak reference count.

function ignis_weak_release(handle: *mut void): void

Decrements the weak reference count and may free the control block.

function ignis_weak_retain(handle: *mut void): void

Increments the weak reference count.

Records

record Rc<T>

Reference-counted shared pointer.

Memory Layout

  Rc { handle } ──────┐
  Rc { handle } ──┐   │
                   │   │
                   v   v
               ┌───────────────────────┐
               │  strong: u32          │  reference counts
               │  weak:   u32          │
               │  drop_fn: fn ptr      │
               ├───────────────────────┤
               │  T payload            │  user data
               └───────────────────────┘

When strong reaches 0, drop_fn runs on the payload. The allocation is freed when both strong and weak reach 0.

Method Reference

Method	Signature	Description
`new`	`(T) -> Rc<T>`	Allocate with strong count 1
`strongCount`	`(&self) -> u32`	Current strong references
`weakCount`	`(&self) -> u32`	Current weak references
`downgrade`	`(&self) -> Weak<T>`	Create a weak observer
`get`	`(&self) -> &T`	Immutable ref to payload
`getMut`	`(&mut self) -> Option<*mut T>`	Mutable access if unique
`clone`	`(&self) -> Rc<T>`	Increment strong, share
`drop`	`(&mut self) -> void`	Decrement strong

Members

handle: *mut void

static new(value: T): Rc<T>

Allocates a new Rc with strong count 1.

Example

import Rc from "std::rc";

let r: Rc<i32> = Rc::new<i32>(100);

clone(&self): Rc<T>

Increments the strong count and returns a new Rc sharing the allocation.

Example

import Rc from "std::rc";

let a: Rc<i32> = Rc::new<i32>(1);
let b: Rc<i32> = a.clone();

downgrade(&self): Weak<T>

Creates a Weak<T> that does not keep the value alive.

Example

import Rc, Weak from "std::rc";

let a: Rc<i32> = Rc::new<i32>(42);
let w: Weak<i32> = a.downgrade();

drop(&mut self): void

Decrements the strong count. Runs the payload destructor when it reaches zero. Frees the allocation when both counts reach zero.

get(&self): &T

Returns an immutable reference to the inner value.

Example

import Rc from "std::rc";

let a: Rc<i32> = Rc::new<i32>(42);
let val: &i32 = a.get();

getMut(&mut self): Option<*mut T>

Returns a mutable pointer to the inner value if this Rc is the sole owner (strongCount == 1), or NONE otherwise.

Example

import Rc from "std::rc";
import Option from "std::option";

let mut a: Rc<i32> = Rc::new<i32>(10);
let ptr: Option<*mut i32> = a.getMut(); // SOME (unique owner)

strongCount(&self): u32

Returns the number of live strong references.

Example

import Rc from "std::rc";

let a: Rc<i32> = Rc::new<i32>(1);
let b: Rc<i32> = a.clone();
let n: u32 = a.strongCount(); // 2

weakCount(&self): u32

Returns the number of live weak references.

Example

import Rc, Weak from "std::rc";

let a: Rc<i32> = Rc::new<i32>(1);
let w: Weak<i32> = a.downgrade();
let n: u32 = a.weakCount(); // 1

record Weak<T>

Non-owning observer of an Rc<T> allocation.

Keeps the allocation header alive so upgrade() can check whether the value still exists. Use Rc::downgrade() to create one.

Lifecycle

  Rc::new(42)        strong=1  weak=0     payload alive
      │
  a.downgrade()      strong=1  weak=1     Weak created
      │
  drop(a)            strong=0  weak=1     payload destroyed
      │
  w.upgrade()        returns NONE         value gone
      │
  drop(w)            strong=0  weak=0     allocation freed

Method Reference

Method	Signature	Description
`upgrade`	`(&self) -> Option<Rc<T>>`	Promote to strong if alive
`weakCount`	`(&self) -> u32`	Current weak references
`strongCount`	`(&self) -> u32`	Current strong references
`clone`	`(&self) -> Weak<T>`	Increment weak, share
`drop`	`(&mut self) -> void`	Decrement weak

Members

handle: *mut void

clone(&self): Weak<T>

Increments the weak count and returns a new Weak sharing the header.

Example

import Rc, Weak from "std::rc";

let a: Rc<i32> = Rc::new<i32>(1);
let w1: Weak<i32> = a.downgrade();
let w2: Weak<i32> = w1.clone();

drop(&mut self): void

Decrements the weak count. Frees the allocation when both counts reach zero.

strongCount(&self): u32

Returns the number of live strong references.

Example

import Rc, Weak from "std::rc";

let a: Rc<i32> = Rc::new<i32>(1);
let w: Weak<i32> = a.downgrade();
let n: u32 = w.strongCount(); // 1

upgrade(&self): Option<Rc<T>>

Attempts to promote this weak reference to a strong Rc<T>.

Returns SOME(Rc<T>) if the value is still alive (strong count > 0), or NONE if all strong references have been dropped.

When successful, the strong count is incremented.

Example

import Rc, Weak from "std::rc";
import Option from "std::option";

let a: Rc<i32> = Rc::new<i32>(42);
let w: Weak<i32> = a.downgrade();
let upgraded: Option<Rc<i32>> = w.upgrade(); // SOME while a is alive

weakCount(&self): u32

Returns the number of live weak references.

Example

import Rc, Weak from "std::rc";

let a: Rc<i32> = Rc::new<i32>(1);
let w: Weak<i32> = a.downgrade();
let n: u32 = w.weakCount(); // 1