Lock Words

A lock enforces mutual exclusion, typically with regard to control of a resource, between multiple tasks. It also serves as a queue for multiple tasks waiting on the lock which is held by another task. Furthermore, it provides a mechanism to avoid priority inversion, by temporarily elevating each task holding a lock’s priority to the maximum priority of all the tasks waiting for it; this applies even when chaining together multiple locks held by tasks holding some locks and waiting on others. Recursive lockings are permitted, with a recursive locking count being maintained by a given lock, which is finally released when all the lockings are matched by releases.

lock

The following words are in lock:

x-not-currently-owned

( – )

Exception raised if a task attempts to unlock a lock it is not the holder of.

lock-size

( – bytes )

Get the size of a lock in bytes.

init-lock

( addr – )

Initialize a lock starting at the specified address addr; note that it must be lock-size bytes in size.

claim-lock

( lock – )

Attempt to acquire a lock lock; if the lock is already held, put the current task in a queue and disable it. In that case, update the priority of the holder of a lock, and any subsequent holders of any locks waited for by the holder of this lock, in order to avoid priority inversion. Note that this must not be called within a critical section. Any number of lockings by the same task are permitted; the lock will be freed when they are balanced by an equal number of releasings.

release-lock

( lock – )

Attempt to release a lock lock if it is not recursively locked; if the current task is not the holder of the lock, raise x-not-currently-owned. If releasing the lock is successful, restore the priority of the current task to what it would be had its priority not been updated in order to avoid priority inversion; afterwards, carry out all the functionality that lock would carry out had it been called by the task at the head of the queue if there is one. If a lock lock is recursively locked, decrement the recursive lock count by one. Note that this must not be called within a critical section.

with-lock

( xt lock – )

Execute an xt with a given lock lock locked while it executes, unlocking it afterwards. If an exception is raised by xt, unlock lock and then re-raise the exception.