Sync: Difference between revisions

From MemCP
Jump to navigation Jump to search
(Created page with "= Sync = The '''Sync''' module provides synchronization and concurrency functionality for the SCM programming language. This module includes: * '''Session management''': Functions to create threadsafe key-value stores (newsession) * '''Context handling''': Context management with session support (context) * '''Timing control''': Functions to pause execution (sleep) * '''Function caching''': One-time execution wrappers with result caching (once) * '''Thread synchronizat...")
 
(Refresh MemCP documentation: accuracy, operational guidance, performance profile and maintained API reference)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
<!-- Copyright (C) 2026 Carl-Philip Haensch -->
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
<span id="sync"></span>
= Sync =
= Sync =


The '''Sync''' module provides synchronization and concurrency functionality for the SCM programming language. This module includes:
<!-- Generated from MemCP c42e19eba on 2026-08-27; do not edit manually. -->
<div class="mw-message-box mw-message-box-notice">Generated from MemCP commit <code>c42e19eba</code> on 27 August 2026. See [[Full SCM API documentation]].</div>
 
The '''Sync''' module provides explicit coordination for state that must cross functional scopes or concurrent tasks. It includes:
 
* thread-safe sessions and contextual values;
* promises and one-time publication;
* mutex and serialized execution helpers;
* shared computation and cache maps;
* timing, waiting, and lifecycle coordination.
 
Prefer ordinary immutable values when no sharing is required. Use these primitives to make ownership, failure, and publication explicit rather than relying on outer-scope mutation, which this Scheme dialect does not provide.
 
== newpromise ==
 
Creates a thread-safe promise that lets parallel work publish one result for other code to inspect. Use it for shared initialization, asynchronous results, or ensuring that only the first successful producer resolves a value. Read with (promise &quot;value&quot;), inspect completion with (promise &quot;state&quot;), resolve with (promise &quot;value&quot; value), resolve exactly once with (promise &quot;once&quot; value), and mark failure with (promise &quot;fail&quot; error).
 
'''Allowed number of parameters:''' 0–1


* '''Session management''': Functions to create threadsafe key-value stores (newsession)
<span id="parameters"></span>
* '''Context handling''': Context management with session support (context)
=== Parameters ===
* '''Timing control''': Functions to pause execution (sleep)
* '''Function caching''': One-time execution wrappers with result caching (once)
* '''Thread synchronization''': Mutex creation for serialized access (mutex)


These functions provide essential tools for managing concurrent operations, shared state, and synchronization in multi-threaded SCM programs.
* '''storage''' (<code>list&lt;any&gt;</code>): optional existing two-item list used to hold the promise state; most callers omit this ''(optional)''
** '''slot''' (<code>any</code>): promise state or value slot


← Back to [[Full SCM API documentation]]
<span id="returns"></span>
=== Returns ===
 
* '''promise''' (<code>func</code>): operation-based accessor for reading, resolving, or failing the promise
** '''Parameters'''
*** '''operation''' (<code>string</code>): one of: value, state, fail, once
*** '''value''' (<code>any</code>): value to store (for value/once/fail) ''(optional)''
*** '''message''' (<code>string</code>): optional error message used when once finds an already completed promise ''(optional)''
** '''Returns'''
*** '''result''' (<code>any</code>): stored value, state flag, or operation result


== newsession ==
== newsession ==


Creates a new session which is a threadsafe key-value store represented as a function that can be either called as a getter (session key) or setter (session key value) or list all keys with (session)
Creates a thread-safe key-value session. Call it without arguments to list values, with a key to read, with a key and value to store, or with get_or_compute_scoped, a scope, a key, and a producer to share one concurrent computation.


'''Allowed number of parameters:''' 0–0
'''Allowed number of parameters:''' 0–0


'''Parameters:'''
<span id="parameters-1"></span>
=== Parameters ===


''This function has no parameters.''
''This function has no parameters.''


'''Returns:''' <code>func</code>
<span id="returns-1"></span>
=== Returns ===
 
* '''session''' (<code>func</code>): session accessor accepting exactly zero, one, two, or four arguments
** '''Parameters'''
*** '''key_or_operation''' (<code>any</code>): key, or get_or_compute_scoped ''(optional)''
*** '''value_or_scope''' (<code>any</code>): value to store, or scope for get_or_compute_scoped ''(optional)''
*** '''scoped_key''' (<code>any</code>): cache key used by get_or_compute_scoped ''(optional)''
*** '''scoped_producer''' (<code>func</code>): producer used only by the four-argument get_or_compute_scoped form ''(optional)''
**** '''Returns'''
***** '''value''' (<code>any</code>): computed value cached for the scope and key
** '''Returns'''
*** '''result''' (<code>any</code>): value list, stored value, retrieved value, or shared computed value
 
== with_session ==
 
Executes a function with the given session installed in the execution context, so storage operations can access the session's transaction state.
 
'''Allowed number of parameters:''' 2–2
 
<span id="parameters-2"></span>
=== Parameters ===
 
* '''session''' (<code>func</code>): the session to install
** '''Parameters'''
*** '''key''' (<code>any</code>) ''(optional)''
*** '''value''' (<code>any</code>) ''(optional)''
** '''Returns'''
*** '''value''' (<code>any</code>)
* '''fn''' (<code>func</code>): the function to execute
** '''Returns'''
*** '''value''' (<code>any</code>)
 
<span id="returns-2"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== context ==
== context ==


Context helper function. Each context also contains a session. (context func args) creates a new context and runs func in that context, (context "session") reads the session variable, (context "check") will check the liveliness of the context and otherwise throw an error
Context helper function. Each context also contains a session. (context func args) creates a new context and runs func in that context, (context &quot;session&quot;) reads the session variable, (context &quot;check&quot;) will check the liveliness of the context and otherwise throw an error
 
'''Allowed number of parameters:''' 0–10000
 
<span id="parameters-3"></span>
=== Parameters ===


'''Allowed number of parameters:''' 1–1000
* '''args...''' (<code>any</code>): depends on the usage ''(variadic)''


'''Parameters:'''
<span id="returns-3"></span>
* '''args...''' (<code>any</code>): depends on the usage
=== Returns ===


'''Returns:''' <code>any</code>
* '''value''' (<code>any</code>)


== sleep ==
== sleep ==
Line 42: Line 112:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-4"></span>
=== Parameters ===
 
* '''duration''' (<code>number</code>): number of seconds to sleep
* '''duration''' (<code>number</code>): number of seconds to sleep


'''Returns:''' <code>bool</code>
<span id="returns-4"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)


== once ==
== once ==
Line 53: Line 128:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-5"></span>
=== Parameters ===
 
* '''f''' (<code>func</code>): function that produces the result value
* '''f''' (<code>func</code>): function that produces the result value
** '''Parameters'''
*** '''argument''' (<code>any</code>) ''(variadic)''
** '''Returns'''
*** '''result''' (<code>any</code>)
<span id="returns-5"></span>
=== Returns ===


'''Returns:''' <code>func</code>
* '''once_wrapper''' (<code>func</code>): calls the wrapped function once and returns its cached result thereafter
** '''Parameters'''
*** '''args''' (<code>any</code>): arguments forwarded to the wrapped function on first call ''(variadic)''
** '''Returns'''
*** '''result''' (<code>any</code>): result cached from the first call


== mutex ==
== mutex ==


Creates a mutex. The return value is a function that takes one parameter which is a parameterless function. The mutex is guaranteed that all calls to that mutex get serialized.
Creates a context-aware mutex. The return value serializes calls to parameterless functions and stops waiting when the current request is cancelled.
 
'''Allowed number of parameters:''' 0–0
 
<span id="parameters-6"></span>
=== Parameters ===
 
''This function has no parameters.''
 
<span id="returns-6"></span>
=== Returns ===
 
* '''locked''' (<code>func</code>): executes one parameterless function while holding the mutex
** '''Parameters'''
*** '''fn''' (<code>func</code>): parameterless function to execute under the lock
**** '''Returns'''
***** '''result''' (<code>any</code>)
** '''Returns'''
*** '''result''' (<code>any</code>): result returned by the protected function
 
== numcpu ==
 
Returns the number of logical CPUs available for parallel execution
 
'''Allowed number of parameters:''' 0–0
 
<span id="parameters-7"></span>
=== Parameters ===
 
''This function has no parameters.''
 
<span id="returns-7"></span>
=== Returns ===
 
* '''value''' (<code>number</code>)
 
== memstats ==
 
Returns memory statistics as a dict with keys: alloc, total_alloc, sys, heap_alloc, heap_sys (all in bytes)
 
'''Allowed number of parameters:''' 0–0
 
<span id="parameters-8"></span>
=== Parameters ===
 
''This function has no parameters.''
 
<span id="returns-8"></span>
=== Returns ===
 
* '''value''' (<code>dict</code>)
 
<span id="settimeout"></span>
== setTimeout ==
 
Schedules a callback to run after the given delay in milliseconds (fractional values allowed for sub-millisecond precision).
 
'''Allowed number of parameters:''' 2–10000
 
<span id="parameters-9"></span>
=== Parameters ===
 
* '''callback''' (<code>func</code>): function to execute once the timeout expires
** '''Parameters'''
*** '''args''' (<code>any</code>) ''(variadic)''
** '''Returns'''
*** '''value''' (<code>any</code>)
* '''milliseconds''' (<code>number</code>): milliseconds until execution
* '''args...''' (<code>any</code>): optional arguments forwarded to the callback ''(variadic)''
 
<span id="returns-9"></span>
=== Returns ===
 
* '''value''' (<code>int</code>)
 
<span id="cleartimeout"></span>
== clearTimeout ==
 
Cancels a timeout created with setTimeout.


'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-10"></span>
=== Parameters ===


''This function has no parameters.''
* '''id''' (<code>number</code>): identifier returned by setTimeout
 
<span id="returns-10"></span>
=== Returns ===


'''Returns:''' <code>func</code>
* '''value''' (<code>bool</code>)

Latest revision as of 11:59, 28 August 2026


Sync

Generated from MemCP commit c42e19eba on 27 August 2026. See Full SCM API documentation.

The Sync module provides explicit coordination for state that must cross functional scopes or concurrent tasks. It includes:

  • thread-safe sessions and contextual values;
  • promises and one-time publication;
  • mutex and serialized execution helpers;
  • shared computation and cache maps;
  • timing, waiting, and lifecycle coordination.

Prefer ordinary immutable values when no sharing is required. Use these primitives to make ownership, failure, and publication explicit rather than relying on outer-scope mutation, which this Scheme dialect does not provide.

newpromise

Creates a thread-safe promise that lets parallel work publish one result for other code to inspect. Use it for shared initialization, asynchronous results, or ensuring that only the first successful producer resolves a value. Read with (promise "value"), inspect completion with (promise "state"), resolve with (promise "value" value), resolve exactly once with (promise "once" value), and mark failure with (promise "fail" error).

Allowed number of parameters: 0–1

Parameters

  • storage (list<any>): optional existing two-item list used to hold the promise state; most callers omit this (optional)
    • slot (any): promise state or value slot

Returns

  • promise (func): operation-based accessor for reading, resolving, or failing the promise
    • Parameters
      • operation (string): one of: value, state, fail, once
      • value (any): value to store (for value/once/fail) (optional)
      • message (string): optional error message used when once finds an already completed promise (optional)
    • Returns
      • result (any): stored value, state flag, or operation result

newsession

Creates a thread-safe key-value session. Call it without arguments to list values, with a key to read, with a key and value to store, or with get_or_compute_scoped, a scope, a key, and a producer to share one concurrent computation.

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • session (func): session accessor accepting exactly zero, one, two, or four arguments
    • Parameters
      • key_or_operation (any): key, or get_or_compute_scoped (optional)
      • value_or_scope (any): value to store, or scope for get_or_compute_scoped (optional)
      • scoped_key (any): cache key used by get_or_compute_scoped (optional)
      • scoped_producer (func): producer used only by the four-argument get_or_compute_scoped form (optional)
        • Returns
          • value (any): computed value cached for the scope and key
    • Returns
      • result (any): value list, stored value, retrieved value, or shared computed value

with_session

Executes a function with the given session installed in the execution context, so storage operations can access the session's transaction state.

Allowed number of parameters: 2–2

Parameters

  • session (func): the session to install
    • Parameters
      • key (any) (optional)
      • value (any) (optional)
    • Returns
      • value (any)
  • fn (func): the function to execute
    • Returns
      • value (any)

Returns

  • value (any)

context

Context helper function. Each context also contains a session. (context func args) creates a new context and runs func in that context, (context "session") reads the session variable, (context "check") will check the liveliness of the context and otherwise throw an error

Allowed number of parameters: 0–10000

Parameters

  • args... (any): depends on the usage (variadic)

Returns

  • value (any)

sleep

sleeps the amount of seconds

Allowed number of parameters: 1–1

Parameters

  • duration (number): number of seconds to sleep

Returns

  • value (bool)

once

Creates a function wrapper that you can call multiple times but only gets executed once. The result value is cached and returned on a second call. You can add parameters to that resulting function that will be passed to the first run of the wrapped function.

Allowed number of parameters: 1–1

Parameters

  • f (func): function that produces the result value
    • Parameters
      • argument (any) (variadic)
    • Returns
      • result (any)

Returns

  • once_wrapper (func): calls the wrapped function once and returns its cached result thereafter
    • Parameters
      • args (any): arguments forwarded to the wrapped function on first call (variadic)
    • Returns
      • result (any): result cached from the first call

mutex

Creates a context-aware mutex. The return value serializes calls to parameterless functions and stops waiting when the current request is cancelled.

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • locked (func): executes one parameterless function while holding the mutex
    • Parameters
      • fn (func): parameterless function to execute under the lock
        • Returns
          • result (any)
    • Returns
      • result (any): result returned by the protected function

numcpu

Returns the number of logical CPUs available for parallel execution

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • value (number)

memstats

Returns memory statistics as a dict with keys: alloc, total_alloc, sys, heap_alloc, heap_sys (all in bytes)

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • value (dict)

setTimeout

Schedules a callback to run after the given delay in milliseconds (fractional values allowed for sub-millisecond precision).

Allowed number of parameters: 2–10000

Parameters

  • callback (func): function to execute once the timeout expires
    • Parameters
      • args (any) (variadic)
    • Returns
      • value (any)
  • milliseconds (number): milliseconds until execution
  • args... (any): optional arguments forwarded to the callback (variadic)

Returns

  • value (int)

clearTimeout

Cancels a timeout created with setTimeout.

Allowed number of parameters: 1–1

Parameters

  • id (number): identifier returned by setTimeout

Returns

  • value (bool)
Retrieved from "https://www.memcp.org/index.php?title=Sync&oldid=362"