"{ 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.
    Any message sent to instances are protected by an internal access lock, 
    to prevent simultaneous access from different threads. 

    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
    "returns the internal lock (an instance of RecursionLock).
     For protocol compatibility with SharedQueue"
    
    ^ accessLock

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

synchronizationSemaphore
    "returns the internal lock (an instance of RecursionLock)"

    ^ accessLock
! !

!SharedCollection methodsFor:'converting'!

asSharedCollection
    "return a shared collection on the receiver.
     because the receiver is already synchronized, itself is returned."

    ^ 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
    "private; initializes the private access lock"

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

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

    ^ accessLock critical:[
        realCollection addFirst:anElement
    ].

    "Created: / 19-03-2020 / 18:28:50 / Stefan Vogel"
!

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

    ^ accessLock critical:[
        realCollection addLast:anElement
    ].

    "Created: / 19-03-2020 / 18:28:03 / Stefan Vogel"
!

at:index
    "retrieve the element at index while locked"

    ^ accessLock critical:[
        realCollection at:index
    ].

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

at:index put:value
    "update the element at index while locked"

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

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

do:aBlock
    "enumerate the elements while locked"

    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,
     and forwards the message to the underlying collection while locked"

    ^ 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$'
! !