Class: SharedCollection

• Inheritance
• Description
• Class protocol
  • instance creation
• Instance protocol
  • accessing
  • converting
  • copying
  • initialization
  • inspecting
  • message forwarding
  • private-accessing
  • queries
  • testing
• Examples

Inheritance:

   Object
   |
   +--Collection
      |
      +--SharedCollection

Package:

stx:libbasic2

Category:

Collections-Support

Version:

rev: 1.43 date: 2024/03/05 18:24:52

user: cg

file: SharedCollection.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

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

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.

Class protocol:

 for: aCollection

create and return a new shareCollection which protects
access to aCollection.
I.e. to return a threadSave accessor on it.

 for: aCollection withLock: aRecursionLock

create and return a new shareCollection which protects
access to aCollection.
I.e. to return a threadSave accessor on it.
Here you can share a common RecursinLock for more than single Collection.

Instance protocol:

 accessLock

marked as obsolete by Stefan Vogel at 22-Mrz-2022

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 synchronizationSemaphore

returns the internal lock (an instance of RecursionLock);
this will be used by synchronized:[...]

 asSharedCollection

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

 shallowCopy

analog to species - copy the real collection

 initializeFor: aCollection

private; initializes the private access lock

 initializeFor: aCollection withLock: aRecursionLock

private; initializes the private access lock

 inspector2TabLabel
( an extension from the stx:libtool package )

label of the main tab

 inspectorClass
( an extension from the stx:libtool package )

redefined to use DictionaryInspector
(instead of the default Inspector).

 inspectorExtraAttributes
( an extension from the stx:libtool package )

extra (pseudo instvar) entries to be shown in an inspector.
Redefined to not block when locked

 inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package )

returns the icon to be shown alongside the value list of an inspector.
Redefined to not block when locked

 inspectorValueStringInListFor: anInspector

returns the value to be shown alongside the value list of an inspector.
Redefined to not block when locked

 add: anElement

add the argument, anObject to the receiver.
Return the added element.

 addFirst: anElement

add the argument, anObject to the front of the receiver.
Return the added element.

 addLast: anElement

add the argument, anObject to the end of the receiver.
Return the added element.

 at: index

retrieve the element at index while locked

 at: index ifAbsent: replacementValue

retrieve the element at index while locked

 at: index ifAbsentPut: value

update the element at index while locked

 at: index put: value

update the element at index while locked

 do: aBlock

enumerate the elements while locked

 doWithExit: aBlock

enumerate the elements while locked

 doWithIndex: aBlock

Squeak/V'Age compatibility;
enumerate the elements while locked.
like keysAndValuesDo:, but passes the index as second argument.
Same as withIndexDo:, due to parallel evolution of different Smalltalk dialects

 doesNotUnderstand: aMessage

catches everything not understood by the collection protocol,
and forwards the message to the underlying collection while locked

 dropAllSuchThat: aBlock

Differs from #removeAllSuchThat:
returns self instead of a collection containing the removed elements.

 isEmpty

for simple collections acquiring the lock
does not make sense. We keep ist here when e.g. LinkedLists have
to be traversed.

 keyAtIdentityValue: aValue ifAbsent: exceptionValue

enumerate the elements while locked

 keysAndValuesDo: aBlock

enumerate the elements while locked

 last

(comment from inherited method)
return the last element of the collection.
This is a slow fallback implementation,
and should be redefined in subclasses which can do indexed accesses.

 notEmpty

for simple collections acquiring the lock
does not make sense. We keep ist here when e.g. LinkedLists have
to be traversed.

 remove: someElement ifAbsent: aBlock

(comment from inherited method)
search for the first element, which is equal to anObject;
if found, remove and return it.
If not found, return the value of the exceptionBlock.
Uses equality compare (=) to search for the occurrence.
An error is raised here - it is to be implemented by a concrete subclass.

 removeAll

(comment from inherited method)
remove all elements from the receiver. Returns the receiver.
This should be reimplemented in subclasses for better
performance.

 removeAllSuchThat: aBlock

(comment from inherited method)
Apply the condition block to each element and remove it if the condition is true.
Return a collection of removed elements.
First elements-to-remove are collected, then removed in one operation.

 removeFirstIfAbsent: aBlock

(comment from inherited method)
remove the first element from the collection; return the removed element.
If there is no element in the receiver collection, return the value from
exceptionBlock.
Destructive: modifies the receiver

 removeIdentical: someElement ifAbsent: aBlock

(comment from inherited method)
search for the first element, which is identical to anObject;
if found, remove and return it.
If not found, return the value of the exceptionBlock.
Uses identity compare (==) to search for the occurrence.
An error is raised here - it is to be implemented by a concrete subclass.

 removeKey: someElement ifAbsent: aBlock

 removeLastIfAbsent: aBlock

 size

for simple collections acquiring the lock does not make sense.
We keep ist here when e.g. LinkedLists have to be traversed.

 subclassResponsibility

catches every required message of the collection protocol

 synchronized: aBlock

(comment from inherited method)
evaluate aBlock synchronized, i.e. use a monitor for this object;
return the value from aBlock

 realCollection

 species

returns non shared collection's species

 isFixedSize

return true if the receiver cannot grow

Examples:

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

        |c|

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