5.5 Stream classes

5.5.3 Locking streams

In an application where more than one control thread may access a common stream, it is important to match the granularity of locking to the transaction model of the application. Ideally, an application should lock a stream which is potentially accessed by multiple threads, only once per transaction. Repeated and unnecessary locking and unlocking can seriously degrade the performance of the Streams module. Thus an application which wishes to write a complex message to a stream that needs to be thread safe should lock the stream, write the message and then unlock the stream after the entire message is written. Locking and unlocking the stream for each character in the message would be a poor match of locking to transaction model. The time required for the lock manipulation would dominate the time required for the stream transactions. Unfortunately this means that there is no way for the Streams module to choose a default locking scheme without the likelihood of seriously degrading streams performance for all applications whose transaction models are different from the model implied by the chosen default locking scheme. Instead, the Streams module provides the user with a single, per instance slot, stream-lock:, which is inherited by all subclasses of <stream>. You should use the generic functions stream-lock and stream-lock-setter, together with other appropriate functions and macros from the Threads library, to implement a locking strategy appropriate to your application and its stream transaction model. The functions in the Streams module are not of themselves thread safe, and make no guarantees about the atomicity of read and write operations.

stream-lock

Open generic function

stream-lock stream => lock

: Returns the lock for the specified stream, or #f if no lock has been set. The lock argument is of type <lock>.

stream-lock-setter

Open generic function

stream-lock-setter stream lock => lock

: Sets the lock for the specified stream. The lock argument is of type <lock>, or #f. If lock is #f, the lock for stream is freed.

For full details on the <lock> class, see the documentation on the Threads library in the Core Features and Mathematics manual.