STREAMS-UX Programmer's Guide (February 2007)

STREAMS Utilities Supported by HP-UX
Appendix B
177
NAME
freezestr () – Freeze the state of a queue.
SYNOPSIS
#include <sys/stream.h>
pl_t freezestr(queue_t *q);
PARAMETERS
q Pointer to a message queue.
DESCRIPTION
For modules/drivers configured at a synchronization level other than SQLVL_NOSYNC, STREAMS/UX uses a
different mechanism to protect the queues. The freezestr() utility in these modules/drivers returns the
current interrupt priority level, and is only provided to make porting code from SVR4 MP easier.
For modules/drivers configured at the synchronization level SQLVL_NOSYNC, freezestr() freezes the state of
the queue specified by q. Freezing a queue blocks everyone except the caller from adding or removing
messages from the queue.
SQLVL_NOSYNC modules and drivers must freeze the queue before calling insq(), rmvq(), strqget(), and
strqset(). Utilities like getq(), putq(), putbq(), flushq(), qsize() etc must not be called by the caller of
freezestr(), while the queue is frozen, as they indirectly freeze the queue to ensure atomicity of queue
manipulation. Calling freezestr() to freeze a queue that is already frozen by the same caller will result in
deadlock.
Freezing the queue does not automatically stop all the functions that are already running in the stream.
Instead, these functions will continue to run until they attempt to perform an operation that changes the
state of the frozen queue. Then, they will be forced to wait for the queue to be unfrozen by a call to
unfreezestr().
It is the responsibility of the caller freezing the queue via freezestr(), to also unfreeze the queue by calling
unfreezestr() after the required operations have been performed on the frozen queue.
freezestr() should be used sparingly. It is rarely necessary to freeze a queue as module/drivers do not need
to manipulate the queues directly. Freezing a queue could have a significant negative impact on performance.
RETURN VALUES
The current interrupt priority level.
CONSTRAINTS
freezestr() can be called from thread or interrupt context. Only spinlocks of STREAMS/UX user lock order
can be held across this call.