package matryoshka
Source

⌘K
Ctrl+K
or
/

    Overview

    Building Blocks for Modular Monoliths in Odin.

    Block 1 — PolyNode + MayItem: item and ownership.

    Block 2 — Mailbox: move items between threads.

    Block 3 — Pool: reuse items.

    Block 4 — Infrastructure as items: mailboxes and pools are items too.

    Open the next block only when you need it.

    Documentation

    Types

    IntrResult ¶
    Source

    IntrResult :: enum untyped integer {
	Ok, 
	Closed, 
	Already_Interrupted, 
}
    Related Procedures With Returns

    Mailbox ¶
    Source

    Mailbox :: ^PolyNode
     

    //////////////////

    Related Procedures With Parameters
    Related Procedures With Returns

    MayItem ¶
    Source

    MayItem :: runtime.Maybe($T=^PolyNode)
     

    ////////////////////////////

    Related Procedures With Parameters

    PolyNode ¶
    Source

    PolyNode :: struct {
	using node: container_intrusive_list.Node,
	// intrusive link — .prev, .next
	tag:  rawptr,
}
     

    PolyNode is the intrusive node embedded at offset 0 in every matryoshka item.

    Embed via using at the first field:

    Chunk :: struct { using poly: PolyNode, // offset 0 — required data: [4096]byte, len: int, }

    With using, field access is promoted: chunk.tag == chunk^.tag. The cast (^Chunk)(node) is valid only when PolyNode is at offset 0. matryoshka has no compile-time check for this — enforced by convention.

    tag rules: - Must be != nil after creation. - nil is always invalid — catches uninitialized nodes. - Tags are static addresses defined by the user per item type.

    Ownership is tracked via MayItem (alias for Maybe(^PolyNode)) at every API boundary:

    m: MayItem

    m^ == nil → not yours (transferred, or nothing here) m^ != nil → you own it — must transfer, recycle, or dispose m == nil → nil handle — invalid; API returns error

    list.Node — one prev/next; a node cannot be in two queues/containers at once. MayItem — nil/non-nil tells every API who holds the item.

    Related Procedures With Parameters
    Related Procedures With Returns

    PolyTag ¶
    Source

    PolyTag :: struct {
	_: u8,
}
     

    PolyTag is the tag type for PolyNode. Each item type defines one private static instance at file scope. The address of that instance is the unique tag for that type. The padding byte ensures each instance has a distinct address.

    Pool ¶
    Source

    Pool :: ^PolyNode
     

    //////////////////

    Related Procedures With Parameters
    Related Procedures With Returns

    PoolHooks ¶
    Source

    PoolHooks :: struct {
	ctx:    rawptr,
	// User-provided context, passed back to hooks.
	tags:   [dynamic]rawptr,
	// Tags of item types this pool manages. All must be != nil.
	on_get: proc(ctx: rawptr, tag: rawptr, in_pool_count: untyped integer, m: ^runtime.Maybe($T=^PolyNode)),
	// Called to create or reinit.
	on_put: proc(ctx: rawptr, in_pool_count: untyped integer, m: ^runtime.Maybe($T=^PolyNode)),
}
     

    PoolHooks defines the user-provided callbacks for managing item lifecycle. Recycler is the implementation of these hooks.

    Related Procedures With Parameters
    Related Procedures With Returns

    Pool_Get_Mode ¶
    Source

    Pool_Get_Mode :: enum untyped integer {
	Available_Or_New, // Use stored item if available, otherwise call on_get to create.
	New_Only,         // Always call on_get with m^ == nil to create a fresh item.
	Available_Only,   // Use stored item only. If empty, return .Not_Available. on_get never called.
}
     

    Pool_Get_Mode determines the behavior of pool_get when no item is available.

    Related Procedures With Parameters

    Pool_Get_Result ¶
    Source

    Pool_Get_Result :: enum untyped integer {
	Ok,             // Success: item returned in m^.
	Not_Available,  // Available_Only mode: no item was stored in the pool.
	Not_Created,    // on_get was called but did not return an item (m^ is nil).
	Closed,         // The pool is closed.
	Already_In_Use, // Entry contract violation: m^ was not nil on call.
}
     

    Pool_Get_Result is the status code returned by pool acquisition operations.

    Related Procedures With Returns

    RecvResult ¶
    Source

    RecvResult :: enum untyped integer {
	Ok, 
	Closed, 
	Interrupted, 
	Already_In_Use, 
	Invalid, 
	Timeout, 
}
    Related Procedures With Returns

    SendResult ¶
    Source

    SendResult :: enum untyped integer {
	Ok, 
	Closed, 
	Invalid, 
}
    Related Procedures With Returns

    Constants

    This section is empty.

    Variables

    MAILBOX_TAG ¶
    Source

    MAILBOX_TAG: rawptr = …

    POOL_TAG ¶
    Source

    POOL_TAG: rawptr = …

    Procedures

    mailbox_is_it_you ¶
    Source

    mailbox_is_it_you :: proc(tag: rawptr) -> bool {…}

    matryoshka_dispose ¶
    Source

    matryoshka_dispose :: proc(m: ^runtime.Maybe($T=^PolyNode)) {…}
     

    matryoshka_dispose is the only way to teardown infrastructure items.

    Entry: - m == nil → no-op - m^ == nil → no-op

    The item must be closed before disposal (mbox_close / pool_close). Panics if the item is still open, or if the tag is not a known system tag.

    Exit: - m^ = nil on success

    mbox_close ¶
    Source

    mbox_close :: proc(mb: ^PolyNode) -> container_intrusive_list.List {…}

    mbox_interrupt ¶
    Source

    mbox_interrupt :: proc(mb: ^PolyNode) -> IntrResult {…}

    mbox_new ¶
    Source

    mbox_new :: proc(alloc: runtime.Allocator) -> ^PolyNode {…}

    mbox_send ¶
    Source

    mbox_send :: proc(mb: ^PolyNode, m: ^runtime.Maybe($T=^PolyNode)) -> SendResult {…}

    mbox_wait_receive ¶
    Source

    mbox_wait_receive :: proc(mb: ^PolyNode, m: ^runtime.Maybe($T=^PolyNode), timeout: time.Duration = -1) -> RecvResult {…}

    polynode_is_linked ¶
    Source

    polynode_is_linked :: proc(n: ^PolyNode) -> bool {…}
     

    polynode_is_linked reports whether n is currently linked into a list. Returns false if n == nil. Used internally as a debug assertion before every insert into infrastructure.

    polynode_reset ¶
    Source

    polynode_reset :: proc(n: ^PolyNode) {…}
     

    polynode_reset clears the intrusive link pointers of n. Safe to call with n == nil (no-op).

    Infrastructure calls this on every single-item return (mbox_wait_receive, pool_get, pool_get_wait). Callers must call it themselves after list.pop_front on batch returns (mbox_close, try_receive_batch, pool_close) before passing to mbox_send or pool_put.

    pool_close ¶
    Source

    pool_close :: proc(p: ^PolyNode) -> (container_intrusive_list.List, ^PoolHooks) {…}
     

    pool_close marks the pool as closed and returns all stored items. Further get/put operations will fail or behave as no-ops.

    pool_get ¶
    Source

    pool_get :: proc(p: ^PolyNode, tag: rawptr, mode: Pool_Get_Mode, m: ^runtime.Maybe($T=^PolyNode)) -> Pool_Get_Result {…}
     

    pool_get acquires an item from the pool.

    pool_get_wait ¶
    Source

    pool_get_wait :: proc(p: ^PolyNode, tag: rawptr, m: ^runtime.Maybe($T=^PolyNode), timeout: time.Duration) -> Pool_Get_Result {…}
     

    pool_get_wait blocks until an item is available in the pool. Never calls on_get.

    pool_init ¶
    Source

    pool_init :: proc(p: ^PolyNode, hooks: ^PoolHooks) {…}
     

    pool_init registers the hooks for the pool. Panics if the pool handle is invalid.

    pool_is_it_you ¶
    Source

    pool_is_it_you :: proc(tag: rawptr) -> bool {…}

    pool_new ¶
    Source

    pool_new :: proc(alloc: runtime.Allocator) -> ^PolyNode {…}
     

    pool_new creates a new Pool instance.

    pool_put ¶
    Source

    pool_put :: proc(p: ^PolyNode, m: ^runtime.Maybe($T=^PolyNode)) {…}
     

    pool_put returns an item to the pool.

    pool_put_all ¶
    Source

    pool_put_all :: proc(p: ^PolyNode, m: ^runtime.Maybe($T=^PolyNode)) {…}
     

    pool_put_all returns a chain of items to the pool.

    Phase 1 validates all tags in the chain before any put — ensures no partial state on bad input. Phase 2 resets each node (clears stale prev/next from the chain linkage) and puts it into the pool.

    try_receive_batch ¶
    Source

    try_receive_batch :: proc(mb: ^PolyNode) -> (container_intrusive_list.List, RecvResult) {…}

    Procedure Groups

    This section is empty.

    Source Files