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

"Make a temporary copy of the set."

| tmp newObjs |

tmp := MyHoldings copy.

"Refresh the snapshot 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’s snapshot 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 14.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 14.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

%

Identifying the Receiving Session

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 14.6 shows how you might use this method to find the session ID for user1 and send a message.

Sending the Message

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

InterSessionSignal class 

	sendSignal: aSignalNumber 

	to: sessionId 

	withMessage: 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.” Your application may use these for specific types of signals, to indicate priority, or whatever other needs your application has; meaning can also be encoded in the message argument.You may create an application-level symbol dictionary of meanings for the different signal numbers.
• sessionId is the sessionId of the session to which the signal will be sent.
• aMessage is a String object with up to 1023 characters.

| sessionId serialNum otherSession signalToSend |

sessionId := System currentSessions

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

     userId = 'TradeUser') ]

	ifNone: [nil].

sessionId ifNotNil: [

	InterSessionSignal 

		sendSignal: 4 

		to: sessionId 

		withMessage: 'reinvest form is here'.

	]

Legacy protocol to send signals

While InterSessionSignal is recommended, you may also use

System sendSignal: aSignalNumber to: sessionId withMessage: aMessage

There are a number of legacy/deprecated ways to signal sessions. These use the serial number of a session rather than the sessionId, or a GsSession instance.

To determine the serial number of a session based on the sessionId, use the following expression:

GsSession 	serialOfSession: sessionId

To loop up a GsSession:

GsSession sessionWithSerialNumber: sessionSerialNumber

Signalling another session can be done using expressions such as:

• GsInterSessionSignal signal: sessionSerialNumber message: aMessage
• signalToSend sendToSession: otherGsSession
• otherGsSession sendSignalObject: signalToSend

No matter how the message is sent, the other session needs to receive it, as shown in Example 14.7.

Example 14.7 Receiving a signal

| theSignal |

theSignal := InterSessionSignal poll.

theSignal ifNotNil: [ 

	theSignal sentInt asString, '-', theSignal sentMessage	]. 

%

4-reinvest form is here

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.

The method InterSessionSignal poll 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 InterSessionSignal poll 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.

Polling

To poll for signals from other sessions, send the following message as often as you require:

InterSessionSignal >> poll

This method returns nil if there is no signal waiting. Example 14.8 shows how to poll for Gem-to-Gem signals. If the polling process finds a signal, it returns; otherwise it sleeps for 10 seconds and tries again. This example includes a limit such that it stops after 10 minutes, if no signal arrives; polling, of course, must continue running.

| theSignal loopLimit |

loopLimit := 0.

[  theSignal := InterSessionSignal poll.

	theSignal notNil and:[ loopLimit < 60 ]

	] whileTrue: [

   		System sleep: 10.

   		loopLimit := loopLimit + 1

   		].

^theSignal

[ 60 timesRepeat: [ 

	InterSessionSignal pollAndSignal.

	System sleep: 10 ]

	] 	on: InterSessionSignal

		do: [:ex | 

			"perform handling for the signal"

			ex resume]

System signalFromGemStoneSession

Receiving a Notification

To use the exception mechanism to receive signals from other Gem sessions without polling, you must enable receipt of the InterSessionSignal notification. By default, the InterSessionSignal notification is disabled, except in the GemBuilder for Smalltalk interface, which enables the error as part of GbsSession>>gemSignalAction:.

When enabled or disabled, the setting is not affected by commits or aborts. It remains until you change it, you end the session, or you receive the error.

To enable this exception, execute:

InterSessionSignal enableSignalling

To disable the exception, send the message:

InterSessionSignal disableSignalling

To determine whether receiving this exception is presently enabled or disabled, send the message:

InterSessionSignal signallingEnabled

If you have enabled signalling on InterSessionSignal, it is automatically disabled when you receive it, so that the exception handler can take appropriate action without further interruption. You must re-enable it afterwards; usually this is the final step in the block that handles the signal.

The following legacy protocol performs the same actions:

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 13, “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 14.10

| theSignal logString |

theSignal := InterSessionSignal poll.

logString := String new.

logString add: '---------------------'; lf;

	add: 'Signal '; 

	add: (theSignal sendInt) asString; 

	add: ' received from session ';

	add: (theSignal sendingSessionId) asString; 

	add: ' with message: '; 

	addAll: (theSignal sentMessage); lf.

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

		addAll: logString; close.