Command: Check out a new lock and get its ID.

((PUB ┆ PRI))
  LOCKNEW

Returns: ID (0-7) of the lock checked out, or -1 if none were available.

Explanation

LOCKNEW is one of four lock commands (LOCKNEW, LOCKRET, LOCKSET, and LOCKCLR) used to manage resources that are user-defined and deemed mutually exclusive. LOCKNEW checks out a unique lock, from the Hub, and retrieves the ID of that lock. If no locks were available, LOCKNEW returns -1.

A user-defined, mutually exclusive resource should be initially set up by a cog, then that same cog should use LOCKNEW to check out a unique lock in which to manage that resource and pass the ID of that lock to any other cogs that require it. For example:

VAR
  byte SemID 

PUB SetupSharedResource 
  <code to set up user-defined, shared resource here>
  if (SemID := locknew) == -1
    <error, no locks available>
  else
    <share SemID's value with other cogs> 

The example above calls LOCKNEW and stores the result in SemID. If that result is -1, an error occurs. If the SemID is not -1, then a valid lock was checked out and that SemID needs to be shared with other cogs along with the address of the resource that SemID is used for. The method used to communicate the SemID and resource address depends on the application, but typically they are both passed as parameters to the Spin method that is launched into a cog, or as the PAR parameter when launching an assembly routine into a cog. See COGNEW for more information.

See also: LOCKRET, LOCKCLR, and LOCKSET.