syncvar: a library of synchronous variables

8.12

syncvar: a library of synchronous variables🔗ℹ

The syncvar library is a library to access synchronous variables inspired by CML.

1 Reference🔗ℹ

This library primarily provides Id style synchronous variables. These variables have two states: empty and full. When a thread attempts to read a variable that is empty the thread will block until it is full. Any attempt to write a value to a full variable will raise an exception.

1.1 IVars🔗ℹ

(require syncvar/ivar)

package: syncvar-lib

An ivar is a write once synchronous variable. Once an ivar is in the full state it cannot go back to the empty state.

In addition to its use with ivar-specific procedures, an ivar can be used as a synchronizable event. An ivar is ready for synchronization when ivar-get would not block; the synchronization result is the same as the ivar-get result.

procedure
(ivar? v) → boolean?
v : any/c

Returns #t if v is a ivar, #f otherwise.

procedure
(make-ivar) → ivar?

Creates an ivar in the empty state.

procedure
(ivar-put! an-ivar v) → any
an-ivar : ivar?
v : any/c

Transitions an-ivar from the empty state to the full state, storing v in it and unblocking any threads waiting to read it. If an-ivar is already in the full state raises an exception.

procedure
(ivar-get an-ivar) → any
an-ivar : ivar?

Waits until an-ivar is in the full state and retrieves the stored value.

procedure
(ivar-try-get an-ivar) → any
an-ivar : ivar?

If an-ivar is in the full state return the stored value, otherwise returns #f.

procedure
(ivar-get-evt an-ivar) → evt?
an-ivar : ivar?

Returns a fresh synchronizable event for use with sync. The event is ready for synchronization when an-ivar is in the full state; the event’s synchronization result is the value stored in an-ivar.

procedure
(exn:fail:ivar? v) → boolean?
v : any/c

A predicate for recognizing exceptions raised when a thread attempts to ivar-put! a full ivar.

1.2 MVars🔗ℹ

(require syncvar/mvar)

package: syncvar-lib

A mvar is a mutable synchronous variable.

procedure
(mvar? v) → boolean?
v : any/c

Returns #t if v is a mvar, #f otherwise.

procedure
(make-mvar [initial-value]) → mvar?
initial-value : any/c = undefined

Creates a mvar. If initial-value is specified then the mvar will be in the full state, otherwise it will be empty.

procedure
(mvar-put! a-mvar v) → void?
a-mvar : mvar?
v : any/c

Transitions a-mvar from the empty state to the full state, storing v in it and unblocking any threads waiting to read it. If a-mvar is already in the full state raises an exception.

procedure
(mvar-take! a-mvar) → any
a-mvar : mvar?

Waits until a-mvar is in a full state, and then transitions it back to the empty state and returns the stored value.

procedure
(mvar-try-take! a-mvar) → any
a-mvar : mvar?

If a-mvar is in the full state, transitions it to the empty state and returns the stored value; otherwise, return #f.

procedure
(mvar-get a-mvar) → any
a-mvar : mvar?

Waits until a-mvar is in the full state and returns the stored value.

procedure
(mvar-try-get a-mvar) → any
a-mvar : mvar?

If a-mvar is in the full state return the stored value, otherwise returns #f.

procedure
(mvar-swap! a-mvar v) → any
a-mvar : mvar?
v : any/c

Waits until a-mvar is in the full state and replaces the stored value with v. Returns the old value stored in a-mvar.

procedure
(mvar-update! a-mvar f) → any
a-mvar : mvar?
f : (-> any/c any)

Waits until a-mvar is in the full state and replaces the stored value with the result of (f old-value). Returns the old value stored in a-mvar.

If an error occurs while running f, then the original value will be stored in a-mvar.

Changed in version 0.9.3 of package syncvar-lib: fixed update error behavior

procedure
(mvar-take!-evt a-mvar) → evt?
a-mvar : mvar?

Returns a fresh synchronizable event for use with sync. The event is ready for synchronization when a-mvar is in the full state; the event’s synchronization result is the value removed from a-mvar.

When this event is ready the stored value will be removed.

procedure
(mvar-get-evt a-mvar) → evt?
a-mvar : mvar?

Returns a fresh synchronizable event for use with sync. The event is ready for synchronization when a-mvar is in the full state; the event’s synchronization result is the value stored in a-mvar.

procedure
(mvar-swap!-evt a-mvar v) → evt?
a-mvar : mvar?
v : any/c

Returns a fresh synchronizable event for use with sync. The event is ready for synchronization when a-mvar is in the full state; the event’s synchronization result is the old value stored in a-mvar.

When this event is ready the value stored in a-mvar will be replaced with the value v.

procedure
(mvar-update!-evt a-mvar f) → evt?
a-mvar : mvar?
f : (-> any/c any)

When this event is ready the value stored in a-mvar will be replaced with a the value returned from applying f to the old value.

If an error occurs while running f, then the original value will be stored in a-mvar.

Changed in version 0.9.3 of package syncvar-lib: fixed update error behavior

procedure
(exn:fail:mvar? v) → boolean?
v : any/c

A predicate for recognizing exceptions raised when a program attempts to mvar-put! a full mvar.

2 Changelog🔗ℹ

2.1 0.9.3🔗ℹ

Release date: 2023/06/07

Fix behavior in mvar-update!-evt when running the update function resulted in an error.

2.2 0.9.2🔗ℹ

Release date: 2023/04/19

Fixed bug in mvar-update!-evt where the previous value was not returned.

2.3 0.9.1🔗ℹ

Release date: 2023/03/09

Bumping version number to be valid.

2.4 0.9.0🔗ℹ

Release date: 2022/12/29

Initial package server release.