Skip to content

Latest commit

 

History

History
98 lines (67 loc) · 2.45 KB

README.md

File metadata and controls

98 lines (67 loc) · 2.45 KB

implicit-context

What's this?

implicit-context is a DUB package implementing an implicit context system for D as a library.

A context is a table of named values, and each thread has a TLS stack of hierarchical contexts. It is similar to namespaces or environment variables, as the top-most name get the lookup.

It is a secondary stack for your program, to be used to pass "contextual" parameters like:

  • Allocators,
  • Loggers,
  • and anything belonging to "context".

This system is inspired by Odin, Scala, and Jai, but without language support:

  • It doesn't change the ABI, nor is there a hidden parameter in function calls.
  • But you need to call context.push() and context.pop() manually, the language will not manage that for you.

Features

  • Set and get context variables.
  • Namespaced look-up, with masking.
  • Hash-based lookup with 64-bit bloom to save on string comparisons.
  • Includes basic contextual APIs built upon implicit-context:
    • Allocator
    • Logger
    • User Pointer
  • D subset: -betterC-compatible, @nogc, nothrow.
    You need TLS and a C runtime though.

Usage

Set a context variable

// Create or update myInt to value 8.
context.set!int("myInt", 8);

Variable names MUST be valid D identifiers, else it's a programming error.

// Crash. "045" is an invalid identifier.
context.set!int("045", 1);

Get a context variable

// Retrieve value of myInt. This value is thread-local.
int myInt = context.get!int("myInt");

When using context.get, an unknown variable identifier is a programming error and would crash:

int myInt = context.get!int("__non_Existing__"); // Crash

Use context.query for an optional variable:

int myInt;
bool found = context.query!int("myInt", myInt);

Note: wrong type size will crash. Type mismatch with right size will silently succeed, currently.

Push and pop context scopes

  • context.push: Push context, begin a new one.
  • context.pop: Pop context, restore previous values.
context.set!int("var", 4);

context.push;
context.set!int("var", 5); // mask former context variable
context.pop;

assert(context.get!int("var") == 4);

Using the Context Allocator API

How to allocate and reallocate:

// Allocate 1024 bytes.
void* p = context.allocator.malloc(1024);

// Change the allocation size to 24 bytes.
context.allocator.realloc(p, 24);

// Free the allocation.
context.allocator.free(p);