12. Signals and Notifiers

Adding an Object to a Notify Set

To add an object to your notify set, use an expression of the form:

System addToNotifySet: aCommittedObject

When you add an object to the notify set, GemStone begins monitoring changes to it immediately.

Most GemStone objects are composite objects, made up of a root object and a few subobjects. Usually you can just ignore the subobjects. However, there are circumstances in which the both the root object and subobjects must appear in the notify set. For details, see Special Classes.

Example 12.1 creates a collection of stock holdings and then creates a notify set for the stocks in the collection. Finally, the session is set to automatically receive the notifier.

"Create a Class to record stock name, number and price"

Object subclass: #Holding

	instVarNames: #('name' 'number' 'price')

	classVars: #()

	classInstVars: #()

	poolDictionaries: {}

	inDictionary: Published.

"Compile accessing methods"

Holding compileAccessingMethodsFor: Holding instVarNames.

"Add a Collection for Holdings to UserGlobals dictionary" 

UserGlobals

   at: #MyHoldings put: IdentityBag new.

"Add some stocks to my collection"

MyHoldings add:

   (Holding new name: #USSteel; number: 1000; price: 50.00).

MyHoldings add:

   (Holding new name: #VMware; number: 50000; price: 95.00).

MyHoldings add:

   (Holding new name: #ATT; number: 100000; price: 30.00).

"Add the collection object to the notify set"

System addToNotifySet: MyHoldings.

(System notifySet) includesIdentical: MyHoldings.

"Enable receipt of signals"

System enableSignaledObjectsError.

Adding a Collection to a Notify Set

To add a collection of objects to your notify set, use an expression like this:

System addAllToNotifySet: aCollectionOfCommittedObjects

This expression adds the elements of the collection to the notify set.

You don’t have to add the collection object itself, but if you do, use addToNotifySet: rather than addAllToNotifySet:.When a collection object is in the notify set, adding elements to the collection or removing elements from it trigger notification. Modifications to the elements do not trigger notification on the collection object; if you want to know when the elements change, you must add them to the notification set.

Example 12.2 shows the notify set containing both the collection object and the elements in the collection.

"Add the stocks in the collection to the notify set"

System addAllToNotifySet: MyHoldings.

System notifySet.

% 

an Array 

  #1 a Holding 

  #2 a Holding 

  #3 a Holding 

"Add the collection object itself to the notify set"

System addToNotifySet: MyHoldings.

System notifySet.

% 

an Array 

  #1 a Holding 

  #2 a Holding 

  #3 a Holding 

  #4 an IdentityBag 

Listing Your Notify Set

To determine the objects in your notify set, execute:

System notifySet

Removing Objects From Your Notify Set

To remove an object from your notify set, use an expression of the form:

System removeFromNotifySet: anObject

To remove a collection of objects from your notify set, use an expression of the form:

System removeAllFromNotifySet: aCollection

This expression removes the elements of the collection. If the collection object itself is also in the notify set, remove it separately, using removeFromNotifySet:.

To remove all objects from your notify set, execute:

System clearNotifySet

Example 12.3

"Make a temporary copy of the set."

| tmp newObjs |

tmp := MyHoldings copy.

"Refresh the view (commit or abort)."

System commitTransaction.

"Get the difference between the old and new sets."

newObjs := (MyHoldings - tmp).

"Add the new elements to the notify set."

newObjs size > 0 ifTrue: [System addAllToNotifySet: newObjs].

You can also identify objects to remove from the notify set by doing the opposite operation:

tmp - MyHoldings

This method could be useful if you are tracking a great many objects and trying to keep the notify set as small as possible.

Note that only IdentityBag and its subclasses understand “-” as a difference operator.

Receiving Object Change Notification

After a commit, each session view is updated. The object server also updates its list of committed objects. This list of objects is compared with the contents of the notify set for each session, and a set of the changed objects for each notify set is compiled.

You can receive notification of committed changes to the objects in your notify set in two ways:

• Enabling automatic notification, which is faster and uses less CPU
• Polling for changes

System enableSignaledObjectsError

System disableSignaledObjectsError

System signaledObjectsErrorStatus

ObjectsCommittedNotification addDefaultHandler: 

	[:ex | 

	| changes |

	changes := System signaledObjects.

	"do something with the changed objects"

	System enableSignaledObjectsError].

Reading the Set of Signaled Objects

The System class>>signaledObjects method reads the incoming changed object signals. This method returns an array, which includes all the objects in your notify set that have changed since the last time you sent signaledObjects in your current session. The array contains objects changed and committed by all sessions, including your own. If more than one session has committed, the OOPs are OR’d together. The elements of the array are arranged in OOP order, not in the order the changes were committed. If none of the objects in your notify set have been changed, the array is empty.

Use a loop to call signaledObjects repeatedly, until it returns an empty collection. The empty collection guarantees that there are no more signals in the queue.

Also see the discussion on Frequently Changing Objects.

Example 12.4

System disableSignaledObjectsError;

   signaledObjectsErrorStatus.

%

"Create a set."

Published at: #Changes put: IdentitySet new.

System commitTransaction.

System addToNotifySet: Changes.

%

"Login a separate session to perform the following"

Changes add: 'here is a change'.

System commitTransaction

%

"In the original session, see the signal"

| mySignaledObjs count |

System abortTransaction.

count := 0 .

[ mySignaledObjs := System signaledObjects.

mySignaledObjs size = 0 and:[ count < 50]

]

  whileTrue: [

   System sleep: 10 .

   count := count + 1

   ].

^ mySignaledObjs.

%

Frequently Changing Objects

If users are committing many changes to objects in your notify set, you may not receive notification of each change. You might not be able to poll frequently enough, or your exception handler might not process the errors it receives fast enough. In such cases, you can miss some intermediate values of frequently changing objects.

Special Classes

Most GemStone objects are composite objects, but for the purposes of notification you can usually ignore this fact. They are almost always implemented so that changes to subobjects affect the root, so only the root object needs to go into the notify set.

Common operations that trigger notification on the root object include:

• Assignment to an instance variable:

name := 'dowJones'

• Updating the indexable portion of an object:

self at: 3 put: 'active'.

• Adding to a collection:

self add: 3.

In a few cases, however, the changes are made only to subobjects. For the following GemStone kernel classes, both the object and the subobjects must appear in the notification set:

• RcQueue
• RcIdentityBag
• RcCounter
• RcKeyValueDictionary

You can also have the problem with your own application classes. Wherever possible, you should implement objects so that changes modify the root object. You must also balance the needs of notification with potential problems of concurrency conflicts.

If you are not being notified of changes to a composite object in your notify set, look at the code and see which objects are actually modified during common operations such as add: or remove:. When you are looking for the code that actually modifies an object, you may have to check a lower-level method to find where the work is performed.

Once you know the object’s structure and have discovered which elements are changed, add the object and its relevant elements to the notify set. For cases where elements are known, you can add them just like any other object:

System addToNotifySet: anObject

Example 12.5 shows a method that creates an object and automatically adds it to the notify set in the process.

method: SetOfHoldings

add: anObject

	System addToNotifySet: anObject.

	^super add: anObject

%

Finding the Session ID

To send a signal to another Gem session, you must know its session ID. To see a description of sessions that are currently logged in, execute the following method:

System currentSessions

This message returns an array of SmallIntegers representing session IDs for all current sessions. Example 12.6 shows how you might use this method to find the session ID for user1 and send a message.

| sessionId serialNum otherSession signalToSend |

  sessionId := System currentSessions

   detect:[:each |(((System descriptionOfSession: each) at: 1)

      userId = 'user1') ]

   ifNone: [nil].

sessionId notNil ifTrue: [

  serialNum := GsSession serialOfSession: sessionId .

  otherSession := GsSession sessionWithSerialNumber: serialNum .

  signalToSend := GsInterSessionSignal signal: 4 

                         message:'reinvest form is here'.

  signalToSend sendToSession: otherSession.  

]

otherSession sendSignalObject: signalToSend 

System sendSignal: aSignalNumber to: otherSession withMessage: aMessage

GsSession currentSession signalFromSession message

%

reinvest form is here

Sending the Message

When you have the session ID, you can use the method

GsInterSessionSignal class>>signal: aSignalNumber message: aMessage.

• aSignalNumber is determined by the particular protocol you arranged at your site and the specific message you wish to send. Sending the integer “1,” for example, doesn’t convey a lot unless everyone has agreed that ”1” means “Ready to trade.” An option is to create an application-level symbol dictionary of meanings for the different signal numbers.
• aMessage is a String object with up to 1023 characters.

Instead of assigning meanings to aSignalNumber, your site might agree that the integer is meaningless, but the message string is to be read as a string of characters conveying the intended message, as in Example 12.8.

For more complex information, the message could be a code where each token conveys its own meaning.

You can use signals to broadcast a message to every user logged in to GemStone. In Example 12.8, one session notifies all current sessions that it has created a new object to represent a stock that was added to the portfolio. In applications that commit whenever a new object is created, this code could be part of the instance creation method for class Holding. Otherwise, it could be application-level code, triggered by a commit.

System currentSessions do: [:each |

	System sendSignal: 8 to: each 

		withMessage: 'new Holding: SallieMae'.].

Receiving a Signal

You can receive a signal from another session in either of two ways: you can poll for such signals, or you can enable notification from GemStone. Signals are queued in the receiving session in the order in which they were received. If the receiving session has inadequate heap space for an incoming signal, the contents of the signal is written to stdout, whether the receiving session has enabled receiving such signals or not. (Both the structure of the signal contents and the process of enabling signals are described in detail in the following sections.)

The method System class>>signalFromGemStoneSession reads the incoming signals, whether you poll or receive a signal. If there are no pending signals, the array is empty.

Use a loop to call signalFromGemStoneSession repeatedly, until it returns a nil. This guarantees that there are no more signals in the queue. If signals are being sent quickly, you may not receive a separate InterSessionSignal for every signal. Or, if you use polling, signals may arrive more often than your polling frequency.

System signalFromGemStoneSession

| response count |

count := 0 .

[ response := System signalFromGemStoneSession.

  response size = 0 and:[ count < 50 ]

] whileTrue: [

   System sleep: 10.

   count := count + 1

   ].

^response

System enableSignaledGemStoneSessionError

System disableSignaledGemStoneSessionError

System signaledGemStoneSessionErrorStatus

Sending Large Amounts of Data

If you want to pass large amounts of data between sessions, sockets are more appropriate than Gem-to-Gem signals. Chapter 11, “File I/O and Operating System Access”, describes the GemStone interface to TCP/IP sockets. That solution does not pass data through the Stone, so it does not create system overload when you send a great many messages or very long ones.

Example 12.10

| gemMessage logString |

gemMessage := System signalFromGemStoneSession.

logString := String new.

logString add: 

'-----------------------------------------------------

The signal '; 

	add: (gemMessage at: 2) asString; 

	add: ' was received from GemStone sessionId = ';

	add: (gemMessage at: 1) asString; 

	add: ' and the message is '; 

	addAll: (gemMessage at: 3).

(GsFile openWriteOnServer: '$GEMSTONE/gemmessage.txt') 

		addAll: logString; close.