Tsctl Locking

libtsctl is design to make it possible to share resources. It does this by allowing resources to be locked. A lock can be a shared lock, such as might be appropriate for reading a value, or it can be an exclusive lock, which would be appropriate for changing a value.

All resources that provide an interface to lock and unlock them must be locked before use and unlocked after use. This is because in some cases the locking mechanism, in addition to acquiring shared or exclusive access to the resource, also performs per access initialization. For instance, multi-function pins are automatically set to the correct function during locking.

From the perspective of a client there are object locks, which in the server ultimately result in one or more system locks being held, under control of the object being locked and any sub-objects it contains. All tsctl objects which provide a Lock function offer the client to hold an object lock on that object. Each class defines the circumstances under which the client must hold an object lock. A client should not hold an object lock any longer than necessary.

• Bus: the Bus lock must be held before while other functions in the Bus are called.

• Time: does not use locks

• Pin: the lock for a given Pin must be held while ModeSet is called on that pin

• DIORaw: the lock for a given DIO must be held while any function is called for it

• DIO: the lock for a given DIO must be held while any function is called for it

• TWI: the TWI lock must be held before other functions in TWI are called.

• CAN does not use locks

• SPI: the SPI lock must be held before other functions in TWI are called.

The Lock function has several flags. (TO DO)

A connection may hold the same lock more than once, a so-called "recursive" lock. Each lock must be released the same number of times as it is acquired before the connection truly has released the lock. In the server, the connection either holds a system lock or it doesn't; the server keeps track of the system lock count and only acquires the system lock if the count is being incremented from zero, and only releases it if the count is being decremented to zero. (UNIMPLEMENTED)

The server automatically releases all locks held by a connection when it detects that the connection has closed and has read all pending opcodes from the connection.

While a connection can hold multiple locks at once, they must be acquired one at a time.

A server object may acquire additional locks during the course of calling other functions in it. If such a call would cause a deadlock an exception will be generated on the connection, which will close the connection. (UNIMPLEMENTED)