# Core Lock Words

Core locks provide a mutual exclusion mechanism between cores while allowing code executing on the same core to access the protected resource in a nested fashion. This is significant if one needs to protect access to a resource within a critical section on a single core, but one needs to ensure the ability to access that resource within an interrupt handler executing within the same resource. Unlike hardwære spinlocks such as that provided by the RP2040 core locks do not occupy any additional hardware resources, and do not require either some sort of allocation mechanism or a fixed set of pre-allocated hardware resources.

### `core-lock`

The following words are in `core-lock`:

##### `core-lock-size`
( -- bytes )

Get the size of a core lock in bytes.

##### `init-core-lock`
( addr -- )

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

##### `claim-core-lock`
( core-lock -- )

Claim a core lock *core-lock* for the current core. If it is already claimed for a core other than the current core, relinquish control of the current core and try again later repeatly until claiming *core-lock* is successful. If, when claimed for the current core it had already been claimed for the current core, increment a nested claim counter. Note that this is not safe to execute within an interrupt handler.

##### `claim-core-lock-spin`
( core-lock -- )

Claim a core lock *core-lock* for the current core. If it is already claimed for a core other than the current core, spin until it is no longer claimed by any core other the current one, and then claim it. If, when claimed for the current core it had already been claimed for the current core, increment a nested claim counter. Note that this is strictly-speaking safe to execute within an interrupt handler, but that is only advisable if *core-lock* is only claimed for very short periods of time, because it will cause the interrupt handler to wait until it cain claim *corelock*.

##### `claim-core-lock-timeout`
( core-lock -- )

Claim a core lock *core-lock* for the current core. If it is already claimed for a core other than the current core, relinquish control of the current core and try again later repeatly until claiming *core-lock* is successful or the current timeout is reached, where then `x-timed-out` is raised. If, when claimed for the current core it had already been claimed for the current core, increment a nested claim counter. Note that this is not safe to execute within an interrupt handler.

##### `release-core-lock`
( core-lock -- )

Release a core lock *core-lock*, decrementing its nested claim counter until it reaches zero. If all previous claims have been balanced, the *core-lock* may now be claimed by a task on another core.

##### `with-core-lock`
( xt core-lock -- )

Execute an execution token *xt* with a given core lock *core-lock* claimed while it executes, releasing it afterwards. If an exception is raised by *xt*, release *core-lock* and then re-raise the exception. Note that this uses the mechanism implemented in `claim-core-lock`, with all of its associated caveats.

##### `with-core-lock-spin`
( xt core-lock -- )

Execute an execution token *xt* with a given core lock *core-lock* claimed while it executes, releasing it afterwards. If an exception is raised by *xt*, release *core-lock* and then re-raise the exception. Note that this uses the mechanism implemented in `claim-core-lock-spin`, with all the associated caveats.