Module coco::epoch

Epoch-based garbage collection.

Pointers

Concurrent collections are built using atomic pointers. This module provides Atomic, which is just a shared atomic pointer to a heap-allocated object. Loading an Atomic yields a Ptr, which is an epoch-protected pointer through which the loaded object can be safely read.

Pinning

Before an Atomic can be loaded, the current thread must be pinned. By pinning a thread we declare that any object that gets removed from now on must not be destructed just yet. Garbage collection of newly removed objects is suspended until the thread gets unpinned.

Garbage

Objects that get removed from concurrent collections must be stashed away until all currently pinned threads get unpinned. Such objects can be stored into a Garbage, where they are kept until the right time for their destruction comes.

There is a global shared instance of Garbage, which can only deallocate memory. It cannot drop objects or run arbitrary destruction procedures. Removed objects can be stored into it by calling defer_free or defer_drop.

Structs

Atomic	An atomic pointer that can be safely shared between threads.
Garbage	[ Deprecated ] A garbage queue.
Owned	An owned heap-allocated object.
Ptr	A pointer to an object protected by the epoch GC.
Scope	A witness that the current thread is pinned.

Functions

is_pinned	Returns true if the current thread is pinned.
pin	Scopes the current thread.
unprotected⚠	Creates an unprotected scope without pinning the current thread.