refman.md

cpp-effects: Reference Manual

Introduction

🚀 Quick intro (and comparison with effectful functional programming) - A brief overview of the API of the library. It assumes that the reader has some basic understanding of algebraic effects and effect handlers.

Structure of the library

Namespace: cpp_effects

📝 cpp-effects/cpp-effects.h - The core of the library:

• class command - Classes derived from command define commands.

• class flat_handler - Version of handler for generic handlers with identity return clause.

• class handler - Classes derived from handler define handlers.

• type handler_ref - Abstract reference to an active handler.

• class resumption - Suspended computation, given to the user in command clauses of a handler.

• classes resumption_data and resumption_base - "Bare" captured continuations that are not memory-managed by the library.

• namespace cpp_effects_internal - Details of the implementation, exposed for experimentation.

• functions:

  • debug_print_metastack - Prints out the current stack of handlers. Useful for "printf" debugging.

  • fresh_label - Generates a unique label that identifies a handler.

  • handle - Creates a new handler object and uses it to handle a computation.

  • handle_ref - Similar to handle, but reveals a reference to the handler.

  • handle_with - Handles a computation using a given handler object.

  • handle_with_ref - Handles a computation using a particular handler object and reveals a reference to the handler.

  • wrap - Lifts a function to a resumption handled by a new handler object.

  • wrap_with - Lifts a function to a resumption handled by a given handler object.

  • invoke_command - Used in a handled computation to invoke a particular command, suspend the computation, and transfer control to the handler.

  • static_invoke_command - Similar to invoke_commad, but explicitly gives the type of the handler object (not type-safe, but more efficient).

📝 cpp-effects/clause-modifiers.h - Modifiers that force specific shapes or properties of command clauses in handlers:

• no_manage - Command clause that does not memory-manage the handler.

• no_resume - Command clause that does not use its resumptions.

• plain - Command clause that interprets a command as a function (i.e., a self- and tail-resumptive clause).