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...")
 
No edit summary
Line 12: Line 12:


← Back to [[Full SCM API documentation]]
← Back to [[Full SCM API documentation]]
== newpromise ==
Creates a single-value promise cell (thread-safe via CAS spin-lock). Returns a tagPromise Scmer. (newpromise) allocates a [2]Scmer backing; (newpromise list) reuses an existing ≥2-element slice as backing with zero extra allocation. API: (p "value") reads current value (nil if pending), (p "value" v) resolves, (p "once" v) resolves once (panics if already fulfilled/failed), (p "once" v msg) resolves once with custom panic message, (p "state") returns state (nil/true/false), (p "fail") sets failed and clears the stored value, (p "fail" err) sets failed and stores err as payload.
'''Allowed number of parameters:''' 0–1
<span id="parameters"></span>
=== Parameters ===
* '''list''' (<code>any</code>): optional: ≥2-element slice to use as backing ''(optional)''
<span id="returns"></span>
=== Returns ===
<code>func(operation:string, value:any?, msg:string?) -&gt; any</code>


== 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 new session which is a threadsafe key-value store. Besides get/set/list, get_or_compute_scoped shares concurrent computation by a query-local handle.


'''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 ===
 
<code>func(key_or_operation:any?, value_scope_or_key:any?, key_or_producer:any?, scoped_producer:func?) -&gt; any</code>
 
== 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(key:any?, value:any?) -&gt; any</code>): the session to install
* '''fn''' (<code>func</code>): the function to execute
 
<span id="returns-2"></span>
=== Returns ===
 
<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:''' 1–1000
'''Allowed number of parameters:''' 0–10000


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


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


== sleep ==
== sleep ==
Line 42: Line 84:
'''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 ===
 
<code>bool</code>


== once ==
== once ==
Line 53: Line 100:
'''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


'''Returns:''' <code>func</code>
<span id="returns-5"></span>
=== Returns ===
 
<code>func(args:any...) -&gt; any</code>


== 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 ===
 
<code>func(fn:func) -&gt; any</code>
 
== 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 ===
 
<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 ===
 
<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(args:any...) -&gt; any</code>): function to execute once the timeout expires
* '''milliseconds''' (<code>number</code>): milliseconds until execution
* '''args...''' (<code>any</code>): optional arguments forwarded to the callback ''(variadic)''
 
<span id="returns-9"></span>
=== Returns ===
 
<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>
<code>bool</code>

Revision as of 08:29, 27 August 2026

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 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.

← Back to Full SCM API documentation

newpromise

Creates a single-value promise cell (thread-safe via CAS spin-lock). Returns a tagPromise Scmer. (newpromise) allocates a [2]Scmer backing; (newpromise list) reuses an existing ≥2-element slice as backing with zero extra allocation. API: (p "value") reads current value (nil if pending), (p "value" v) resolves, (p "once" v) resolves once (panics if already fulfilled/failed), (p "once" v msg) resolves once with custom panic message, (p "state") returns state (nil/true/false), (p "fail") sets failed and clears the stored value, (p "fail" err) sets failed and stores err as payload.

Allowed number of parameters: 0–1

Parameters

  • list (any): optional: ≥2-element slice to use as backing (optional)

Returns

func(operation:string, value:any?, msg:string?) -> any

newsession

Creates a new session which is a threadsafe key-value store. Besides get/set/list, get_or_compute_scoped shares concurrent computation by a query-local handle.

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

func(key_or_operation:any?, value_scope_or_key:any?, key_or_producer:any?, scoped_producer:func?) -> any

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(key:any?, value:any?) -> any): the session to install
  • fn (func): the function to execute

Returns

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

any

sleep

sleeps the amount of seconds

Allowed number of parameters: 1–1

Parameters

  • duration (number): number of seconds to sleep

Returns

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

Returns

func(args:any...) -> any

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

func(fn:func) -> any

numcpu

Returns the number of logical CPUs available for parallel execution

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

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

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(args:any...) -> any): function to execute once the timeout expires
  • milliseconds (number): milliseconds until execution
  • args... (any): optional arguments forwarded to the callback (variadic)

Returns

int

clearTimeout

Cancels a timeout created with setTimeout.

Allowed number of parameters: 1–1

Parameters

  • id (number): identifier returned by setTimeout

Returns

bool

Retrieved from "https://www.memcp.org/index.php?title=Sync&oldid=289"