Semaphore library - locking and synchronization mechanism for scripts #

Load the library:


Library functions #

sem.runlocked(name, timeout, callback, [param1, [param2, [...]]]) #

Runs callback function in locked mode, returning all callback results as is. First parameter passed to callback is lock status - true when lock was acquired, false when locking failed, nil when semaphore creation failed.


  • name - shared semaphore name
  • timeout - maximum time to wait in seconds for semaphore to become unlocked
  • callback - function to execute in locked mode
  • param1, param2, ... - optional additional parameters to pass to callback

Example (event script with locking):


-- wait for 5 seconds max before executing callback
res1, res2 = sem.runlocked('eventlock', 5, function(lockres)
  -- lock acquired
  if lockres then
    return true, 'lock ok'
  -- failed to acquire lock
    return nil, 'lock failed'

log(res1, res2)

semaphore =, [value = 1]) #

Opens shared semaphore, returns semaphore handle or generates an error on failure.


  • name - shared semaphore name, required
  • value - initial value, optional, defaults to 1 (semaphore is unlocked)

semaphore:getvalue() #

Returns the current value of the semaphore or nil on error. Zero value means that the semaphore is locked.

semaphore:post() #

Increments (unlocks) the semaphore.

semaphore:trywait() #

Checks if the semaphore is locked, returns true and decrements the semaphore when the value is non-zero, false otherwise.

semaphore:wait([timeout]) #

Decrements the semaphore with optional timeout in seconds.

When no timeout is specified, this function will block until semaphore is incremented.

semaphore:close() #

Closes the semaphore. Not required, semaphore handles are closed automatically when script execution ends.