"
 COPYRIGHT (c) 1993 by Claus Gittinger
	      All Rights Reserved

 This software is furnished under a license and may be used
 only in accordance with the terms of that license and with the
 inclusion of the above copyright notice.   This software may not
 be provided or otherwise made available to, or used by, any
 other person.  No title to or ownership of the software is
 hereby transferred.
"

Queue subclass:#SharedQueue
	instanceVariableNames:'accessProtect dataAvailable spaceAvailable'
	classVariableNames:''
	poolDictionaries:''
	category:'Kernel-Processes'
!

!SharedQueue class methodsFor:'documentation'!

copyright
"
 COPYRIGHT (c) 1993 by Claus Gittinger
	      All Rights Reserved

 This software is furnished under a license and may be used
 only in accordance with the terms of that license and with the
 inclusion of the above copyright notice.   This software may not
 be provided or otherwise made available to, or used by, any
 other person.  No title to or ownership of the software is
 hereby transferred.
"
!

documentation
"
    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.

    See samples in doc/coding.

    [author:]
        Claus Gittinger

    [see also:]
        Semaphore
        Process
        CodingExamples::SharedQueueExamples
"
! !

!SharedQueue methodsFor:'accessing'!

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"

    |value ok|

    ok := false.
    [ok] whileFalse:[
	[tally == 0] whileTrue:[
	    dataAvailable wait
	].
	accessProtect critical:[
	    "
	     this check is needed, since another process may
	     have read the value in the meantime ...
	    "
	    tally == 0 ifFalse:[
		value := super next.
		tally == (contentsArray size - 1) ifTrue:[
		    spaceAvailable signal
		].
		ok := true
	    ]
	]
    ].
    ^ value
!

nextPut:anObject
    "enter anObject into the queue; wait for available space, if
     the queue is full. After the put, signal availablity of a datum
     to readers."

    |ok|

    ok := false.
    [ok] whileFalse:[
	[tally == contentsArray size] whileTrue:[
	    spaceAvailable wait
	].
	accessProtect critical:[
	    tally == contentsArray size ifFalse:[
		super nextPut:anObject.
		tally == 1 ifTrue:[
		    dataAvailable signal
		].
		ok := true
	    ]
	]
    ].
    ^ anObject
!

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

    ^ dataAvailable

    "Modified: 16.12.1995 / 13:47:11 / cg"
!

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."

    accessProtect critical:[
        |oldCount|

        oldCount := tally.
        super removeAll.
        oldCount == (contentsArray size) ifTrue:[
            spaceAvailable signal
        ].
    ].

!

removeLast
    "return the last 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"

    |value ok|

    ok := false.
    [ok] whileFalse:[
        [tally == 0] whileTrue:[
            dataAvailable wait
        ].
        accessProtect critical:[
            "
             this check is needed, since another process may
             have read the value in the meantime ...
            "
            tally == 0 ifFalse:[
                value := super removeLast.
                tally == (contentsArray size - 1) ifTrue:[
                    spaceAvailable signal
                ].
                ok := true
            ]
        ]
    ].
    ^ value

    "Created: 22.6.1996 / 18:50:12 / cg"
!

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

    ^ spaceAvailable

    "Modified: 16.12.1995 / 13:47:07 / cg"
! !

!SharedQueue methodsFor:'initialization'!

init:size
    "initialize the receiver for size entries"

    super init:size.
    accessProtect := Semaphore forMutualExclusion name:'shared q-access'.
    dataAvailable := Semaphore new name:'shared q-read'.
    spaceAvailable := Semaphore new name:'shared q-write'

    "Modified: 25.1.1997 / 00:19:45 / cg"
! !

!SharedQueue class methodsFor:'documentation'!

version
    ^ '$Header: /cvs/stx/stx/libbasic2/SharedQueue.st,v 1.20 1998-05-21 10:52:49 ca Exp $'
! !