"{ Encoding: utf8 }"

"
 COPYRIGHT (c) 2006 by eXept Software AG
              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.
"
"{ Package: 'stx:libbasic2' }"

"{ NameSpace: Smalltalk }"

Collection subclass:#SharedCollection
	instanceVariableNames:'accessLock realCollection'
	classVariableNames:''
	poolDictionaries:''
	category:'Collections-Support'
!

!SharedCollection class methodsFor:'documentation'!

copyright
"
 COPYRIGHT (c) 2006 by eXept Software AG
              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
"
    Instances of this class provide synchronized access (of multiple processes) 
    to a collection.

    Notice: 
        the message-forwarding is done by catching subclassResponsibility and
        doesNotUnderstand errors.

    For performance, and for more complex operation-atomicy, more messages might need
    an explicit handling. 
    See the implementation of #at: / #at:put: and #size for examples.

    [auhor:]
        Claus Gittinger

    [see also:]
        Semaphore RecursionLock
        SharedQueue
        #synchronized: method in Object.
"
!

examples
"
                                        [exBegin]
        |c|

        c := SharedCollection for:(OrderedCollection new).
        c add:1.
        c add:2.
        c add:3.
        c addAll:#(4 5 6).
        c removeFirst.
        c removeLast.
        c inspect.
                                        [exEnd]

                                        [exBegin]
        |c|

        c := SharedCollection for:(Array new:10).
        c at:1 put:5.
        c replaceFrom:2 to:5 with:#(20 30 40 50).
        c inspect.
                                        [exEnd]
"
! !

!SharedCollection class methodsFor:'instance creation'!

for:aCollection
    "create and return a new shareCollection which protects
     access to aCollection.
     I.e. to return a threadSave accessor on it."
     
    ^ self new initializeFor:aCollection

    "Modified (comment): / 18-02-2017 / 10:49:03 / cg"
! !

!SharedCollection methodsFor:'accessing'!

accessLock
    "for protocol compatibility with SharedQueue"
    
    ^ accessLock

    "Created: / 04-05-2019 / 12:32:15 / Claus Gittinger"
!

synchronizationSemaphore
    ^ accessLock
! !

!SharedCollection methodsFor:'converting'!

asSharedCollection
    ^ self.
! !

!SharedCollection methodsFor:'copying'!

shallowCopy
    "analog to species - copy the real collection"

    ^ accessLock critical:[
        "get a consistent copy"
        realCollection shallowCopy
    ].

    "Modified: / 02-02-2017 / 17:03:55 / stefan"
! !

!SharedCollection methodsFor:'initialization'!

initializeFor:aCollection
    accessLock := RecursionLock name:'SharedCollection'.
    realCollection := aCollection.

    "Modified: / 23-02-2017 / 12:41:45 / stefan"
    "Modified: / 09-08-2017 / 11:59:29 / cg"
! !

!SharedCollection methodsFor:'message forwarding'!

add:anElement
    "add the argument, anObject to the receiver.
     Return the added element."

    ^ accessLock critical:[
        realCollection add:anElement
    ].

    "Modified: / 02-02-2017 / 17:01:08 / stefan"
!

at:index
    ^ accessLock critical:[
        realCollection at:index
    ].

    "Modified: / 02-02-2017 / 17:01:23 / stefan"
!

at:index put:value
    ^ accessLock critical:[
        realCollection at:index put:value
    ].

    "Modified: / 02-02-2017 / 17:01:35 / stefan"
!

do:aBlock
    ^ accessLock critical:[
        realCollection do:aBlock
    ].

    "Created: / 22-11-2010 / 21:01:21 / cg"
    "Modified: / 02-02-2017 / 17:02:00 / stefan"
!

doesNotUnderstand:aMessage
    "catches everything not understood by the collection protocol"

    ^ accessLock critical:[
        aMessage sendTo:realCollection
    ].

    "Modified: / 07-12-2006 / 17:38:30 / cg"
    "Modified: / 02-02-2017 / 17:02:18 / stefan"
!

isEmpty
    ^ accessLock critical:[
        realCollection isEmpty
    ].

    "Created: / 22-11-2010 / 20:59:01 / cg"
    "Modified: / 02-02-2017 / 11:40:56 / stefan"
!

last
    ^ accessLock critical:[
        realCollection last
    ].

    "Created: / 06-05-2019 / 18:51:26 / Claus Gittinger"
!

notEmpty
    ^ accessLock critical:[
        realCollection notEmpty
    ].

    "Created: / 22-11-2010 / 20:59:06 / cg"
    "Modified: / 02-02-2017 / 17:00:36 / stefan"
!

remove:someElement ifAbsent:aBlock
    ^ accessLock critical:[
        realCollection remove:someElement ifAbsent:aBlock
    ].

    "Created: / 25-01-2017 / 22:57:32 / stefan"
    "Modified: / 02-02-2017 / 17:00:54 / stefan"
!

removeAllSuchThat:aBlock
    ^ accessLock critical:[
        realCollection removeAllSuchThat:aBlock
    ].

    "Created: / 22-11-2010 / 20:59:27 / cg"
    "Modified: / 02-02-2017 / 17:02:38 / stefan"
!

removeIdentical:someElement ifAbsent:aBlock
    ^ accessLock critical:[
       realCollection removeIdentical:someElement ifAbsent:aBlock
    ].

    "Created: / 22-11-2010 / 21:00:33 / cg"
    "Modified: / 02-02-2017 / 17:02:52 / stefan"
!

size
    ^ accessLock critical:[
        realCollection size
    ].

    "Modified: / 02-02-2017 / 17:03:06 / stefan"
!

subclassResponsibility
    "catches every required message of the collection protocol"

    |msg|

    msg := thisContext sender message.
    ^ accessLock critical:[
        msg sendTo:realCollection
    ].

    "Modified: / 02-02-2017 / 17:03:25 / stefan"
! !

!SharedCollection methodsFor:'queries'!

species
    "returns non shared collection's species"

    ^ realCollection species
! !

!SharedCollection methodsFor:'testing'!

isFixedSize
    "return true if the receiver cannot grow"

    ^ realCollection isFixedSize
! !

!SharedCollection class methodsFor:'documentation'!

version
    ^ '$Header$'
!

version_CVS
    ^ '$Header$'
! !