Class: SharedQueue

• Inheritance
• Description
• Related information
• Instance protocol
  • accessing
  • accessing-internals
  • accessing-reading
  • adding
  • enumerating
  • initialization
  • private
• Examples

Inheritance:

   Object
   |
   +--Collection
      |
      +--Queue
         |
         +--SharedQueue
            |
            +--UnlimitedSharedQueue

Package:

stx:libbasic2

Category:

Kernel-Processes

Version:

rev: 1.50 date: 2018/05/24 19:17:36

user: cg

file: SharedQueue.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Author:

Claus Gittinger

Description:

SharedQueues provide a safe mechanism for processes to communicate.
They are basically Queues, with added secure access to the internals,
allowing use from multiple processes (i.e. the access methods use
critical regions to protect against confusion due to a process
switch within a modification).

Also, sharedQueues can be used for synchronization, since a reading
process will be blocked when attempting to read an empty queue, while
a writer will be blocked when attempting to write into a full queue.
For nonBlocking read, use #isEmpty; for nonBlocking write, use #isFull.

Be warned:
    if the reader process wants to add elements to the sharedqueue in its
    read-loop, the reader may block, if the queue is full.
    The reason is that the sharedQueues size is fixed, and any writer is blocked
    if the queue is full.
    For this situations, please use an UnlimitedSharedQueue, which grows in this
    particular situation.
    
See samples in doc/coding.

Related information:

    SharedCollection
    UnlimitedSharedQueue
    Queue
    Semaphore
    Process
    CodingExamples::SharedQueueExamples

Instance protocol:

 remove: anElement ifAbsent: exceptionalValue

(comment from inherited method)
remove and return a particular element from the queue;
Return the value from exceptionalValue if the element is not in the queue

 removeAll

remove all elements in the queue; do not wait, but
synchronize access to the queue.
If the queue was full before, signal space-availability to writers.
This can be used to flush queues in multi-process applications,
when cleanup is required.

 removeIdentical: anElement ifAbsent: exceptionalValue

(comment from inherited method)
remove and return a particular element from the queue;
Return the value from exceptionalValue if the element is not in the queue

 removeLast

return the last value in the queue; if it its empty, wait until
something is put into the receiver.
When the datum has been removed, signal space-availability to
writers

 accessLock

return the critical access-semaphore which is used internally to synchronize access

 readSemaphore

return the semaphore which is signalled when data is available
for reading.

 readWaitWithTimeoutMs: ms

Return true if a timeout occurred (i.e. false, if data is available).

 superNextPut: anObject

private; to allow subclasses to call the basic nextPut (w.o. synchronization)

 superNextPutFirst: anObject

private; to allow subclasses to call the basic nextPutFirst (w.o. synchronization)

 withAccessLockedDo: aBlock

evaluate aBlock while access via next/nextPut are blocked.

 writeSemaphore

return the semaphore which is signalled when the queue has space
for writing.

 next

return the next value in the queue; if it its empty, wait 'til
something is put into the receiver.
When the datum has been removed, signal space-availability to
writers

 nextIfEmpty: exceptionBlock

return the next value in the queue;
if it is empty do not wait, but return the value of exceptionBlock.
When a datum has been removed, signal space-availability to writers

 nextOrNil

(comment from inherited method)
return the next value in the queue;
Return nil, if the queue is empty

 nextWithTimeout: seconds

return the next value in the queue; if it its empty, wait until
something is put into the receiver.
When the datum has been removed, signal space-availability to
writers.
Timeout after secondsIn seconds - answer nil if a timeout occurs.

 peek

 nextPut: anObject

enter anObject to the end of the queue;
Wait for available space, if the queue is full.
After the put, signal availablity of a datum to readers.

 nextPutFirst: anObject

insert anObject at the beginning of the queue;
Wait for available space, if the queue is full.
After the put, signal availablity of a datum to readers.
Insertion at the beginning may be useful to add hi-prio elements (for example, in a job-scheduler)

 do: anObject

evaluate the argument, aBlock for each element in the queue

 reverseDo: anObject

evaluate the argument, aBlock for each element in the queue

 init: size

initialize the receiver for size entries

 commonWriteWith: aBlock

common code for nextPut / nextPutFirst;
wait for available space, if the queue is full.
After the put, signal availablity of a datum to readers.

Examples: