Module system.sync

The sync library exposes interfaces for various synchronization structures.

Index

Function

lockGuard()	Calls a function, ensuring that the mutex is locked before calling and unlocked after calling, even if the function returns early or throws an error.
synctab()	Creates a new synchronized table. A synchronized table is a table that's protected by a mutex. The table can only be accessed by calling it as a function, which will lock the mutex and calls the callback with the table.

Class

barrier	A barrier is a lock that waits for a specific number of threads to wait on the object, at which point all threads will be released together.
conditionVariable	A condition variable allows threads to wait until another thread notifies them to resume.
mutex	A mutex is an object that controls access to a variable across multiple threads. It ensures only one thread accesses a resource at a time by blocking other threads from locking the mutex until the current thread unlocks it.
rwLock	A readers-writer lock implements two related locks: a read lock, which can be held by multiple threads, and a write lock, which can only be held by one thread. Multiple threads can hold a read lock, but a write lock blocks both read and write locks.
semaphore	A semaphore controls access to a limited number of resources. A function may acquire a resource from the semaphore, decrementing its available count. If the count is zero, it waits until another function releases a resource, at which point it will acquire it and return.

API Reference

class system.sync.mutex

A mutex is an object that controls access to a variable across multiple threads. It ensures only one thread accesses a resource at a time by blocking other threads from locking the mutex until the current thread unlocks it.

staticmethod new(recursive?: boolean): (result: system.sync.mutex)

Creates a new mutex.

Parameters:

recursive? (boolean) – Whether to make the mutex recursive

Returns:

result (system.sync.mutex) – The new mutex object

lock(self: system.sync.mutex): unknown

Locks the mutex, waiting if it’s currently owned by another thread.

unlock(self: system.sync.mutex): unknown

Unlocks the mutex. This is only valid from the thread that owns the lock.

tryLock(self: system.sync.mutex): (result: boolean)

Tries to lock the thread, returning false if it could not be locked.

Returns:

result (boolean) – Whether the mutex is now locked

tryLockFor(self: system.sync.mutex, timeout: number): (result: boolean)

Locks the mutex, waiting until it’s unlocked or until the specified timeout.

Parameters:

timeout (number) – The number of seconds to wait

Returns:

result (boolean) – Whether the mutex is now locked

class system.sync.semaphore

A semaphore controls access to a limited number of resources. A function may acquire a resource from the semaphore, decrementing its available count. If the count is zero, it waits until another function releases a resource, at which point it will acquire it and return.

staticmethod new(init?: number): (result: system.sync.semaphore)

Creates a new semaphore.

Parameters:

init? (number) – The initial count of the semaphore (defaults to 1)

Returns:

result (system.sync.semaphore) – The new semaphore object

acquire(self: system.sync.semaphore): unknown

Acquires a resource from the semaphore, waiting until there is one available.

tryAcquireFor(self: system.sync.semaphore, timeout: number): (result: boolean)

Acquires a resource from the semaphore, waiting until there is one available or until a timeout.

Parameters:

timeout (number) – The number of seconds to wait

Returns:

result (boolean) – Whether the resource was acquired

release(self: system.sync.semaphore): unknown

Releases a resource to the semaphore. This can be called from any thread.

class system.sync.conditionVariable

A condition variable allows threads to wait until another thread notifies them to resume.

staticmethod new(): (result: system.sync.conditionVariable)

Creates a new condition variable.

Returns:

result (system.sync.conditionVariable) – The new condition variable.

wait(self: system.sync.conditionVariable)

Waits for a notification from another thread.

waiting: unknown

waitFor(self: system.sync.conditionVariable, timeout: number): (result: boolean)

Waits for a notification from another thread, or until a timeout occurs.

Parameters:

timeout (number) – The number of seconds to wait

Returns:

result (boolean) – Whether a notification occurred

notifyOne(self: system.sync.conditionVariable)

Notifies a single (unspecified) thread to continue.

notifyAll(self: system.sync.conditionVariable)

Notifies all waiting threads to continue.

class system.sync.barrier

A barrier is a lock that waits for a specific number of threads to wait on the object, at which point all threads will be released together.

staticmethod new(count: number): (result: system.sync.barrier)

Creates a new barrier object.

Parameters:

count (number) – The number of threads to wait for

Returns:

result (system.sync.barrier) – A new barrier object

wait(self: system.sync.barrier): (result: boolean)

Adds one to the thread wait count, and waits until it meets the limit.

Returns:

result (boolean) – Whether this call directly resulted in the barrier being met

left: unknown

cycles: unknown

class system.sync.rwLock

A readers-writer lock implements two related locks: a read lock, which can be held by multiple threads, and a write lock, which can only be held by one thread. Multiple threads can hold a read lock, but a write lock blocks both read and write locks.

staticmethod new(): (result: system.sync.rwLock)

Creates a new RW lock.

Returns:

result (system.sync.rwLock) – The new RW lock

lockRead(self: system.sync.rwLock)

Acquires the lock for reading, waiting for the write lock to be released first.

count: unknown

unlockRead(self: system.sync.rwLock)

Releases the lock for reading.

lockWrite(self: system.sync.rwLock)

Acquires the lock for writing, waiting for the read and write locks to be released.

unlockWrite(self: system.sync.rwLock)

Releases the lock for writing.

system.sync.lockGuard(mutex: system.sync.mutex, fn: function, ...: any): (...: any)

Calls a function, ensuring that the mutex is locked before calling and unlocked after calling, even if the function returns early or throws an error.

Parameters:

• mutex (system.sync.mutex) – The mutex to lock

• fn (function) – The function to call

• ... (any) – Any parameters to pass

Returns:

... (any) – The return values from the function

system.sync.synctab(): (result: fun(callback: fun(any: any): any))

Creates a new synchronized table. A synchronized table is a table that’s protected by a mutex. The table can only be accessed by calling it as a function, which will lock the mutex and calls the callback with the table.

Returns:

result (fun(callback: fun(any: any): any)) – The accessor for the variable