Module Rc

import { Rc, Weak, RcInfo } from "@binarymuse/ts-stdlib";
Copy

(See Rc for the Rc API)

Overview

A reference-counted object provides a way to manage shared resources that need cleanup when they're no longer in use. There are two types of references:

1. Strong references (Rc<T>):

   • Created with Rc() or Rc.clone()
   • Keep the resource alive as long as at least one strong reference exists
   • Must be explicitly disposed with Rc.dispose() when no longer needed

2. Weak references (Weak<T>):

   • Created with Rc.weak() or Rc.intoWeak()
   • Don't prevent the resource from being cleaned up
   • Can be upgraded to strong references with Rc.upgrade() if the resource is still alive

When the last strong reference to a resource is disposed, the resource's cleanup function will be called automatically. Weak references can still exist at this point, but they can no longer be upgraded to strong references.

An Rc<T> is a proxy to the inner object, so you can use the Rc to access all the properties and methods of the inner object (assuming the reference is not disposed).

Example:

const resource = Rc(connection, conn => conn.close());
resource.query("SELECT count(*) FROM users");

// Creates another strong reference
const ref2 = Rc.clone(resource);
// Creates a weak reference
const weak = Rc.weak(resource);

// Resource stays alive (ref2 exists)
Rc.dispose(resource);
// Returns Some(Rc<T>) (resource still alive)
const upgraded = Rc.upgrade(weak);
// Resource is cleaned up
Rc.dispose(ref2);
// Returns None (resource disposed)
const failed = Rc.upgrade(weak);
Copy

The intoWeak function is a special case that:

1. Creates a new weak reference
2. Disposes the original strong reference
3. Returns the weak reference

This is equivalent to, but more efficient than:

const weak = Rc.weak(resource);
Rc.dispose(resource);
return weak;
Copy