3. Sharing Objects

Suppressing Instance Variables

Some client Smalltalk objects must define instance variables that are relevant only in the client environment—for example, a reference to a window object. Such data is transient and doesn’t need to be visible to the GemStone server. Situations can also arise in which the server class defines instance variables that a given application will never need; many applications can share repository objects without necessarily sharing the same concerns. Mapping allows your application to prune parts of an object.

Suppress the replication of an individual instance variable simply by omitting its name from its counterpart’s class definition:

• If a client object contains a named instance variable that does not exist in its GemStone server counterpart, the value of that variable is not replicated in the server. When GemBuilder faults the server object into the client, the client’s suppressed instance variable remains unchanged.
• Likewise, if a server object contains a named instance variable that does not exist in its client counterpart, the value of that variable is not replicated in the client. When GemBuilder flushes the object into the server, the server object’s suppressed instance variable remains unchanged.

You can also suppress instance variable mappings by implementing the client class method instVarMap. For example:

TestObject class>>instVarMap

	^super instVarMap ,

		#(	(nil serverName)

		 	(clientName nil) )

The first component of the return value, a call to super instVarMap, ensures that all instance variable mappings established in superclasses remain in effect.

Appended to the inherited instance variable map, an array contains the pairs of instance variable names to map. The first pair (nil serverName) specifies that the server instance variable serverName will never be replicated in the client. The second pair (clientName nil) specifies that the client instance variable clientName will never be replicated in the server.

Nonmatching Names

You can also specify an explicit instance variable mapping between the server and the client:

• to map two instance variables whose names don’t match, or
• to prevent the mapping of two instance variables whose names do match.

In this way your application can accommodate differing schemas.

To specify mappings from one instance variable name to another, specify each name in the mapping array. For example:

TestObject class>>instVarMap

	^super instVarMap ,

		#(	(clientName  serverName) )

Appended to the inherited instance variable map, a single pair declares that the instance variable clientName in the client maps to the instance variable serverName in GemStone.

One implementation can both prune irrelevancy and accommodate differing schemas. for example,

Book class>>instVarMap

	^super instVarMap ,

		#(	(title title)

		 	(author author)

		 	(nil pages)

		 	(publisher nil)

		 	(copyright publicationDate) )

The first two pairs of instance variables change nothing: they explicitly state what would happen without this method, but are included for completeness.

(nil pages) specifies that the client application does not need to know a books page count and therefore this server-side instance variable is not replicated in the client.

(publisher nil) specifies that the client application needs (and presumably assigns) the instance variable publisher, which is never replicated in the server.

(copyright publicationDate) maps the client class Book’s instance variable copyright to the server class Book’s instance variable publicationDate.

Faulting at Login

At login, the connectors connect, and objects a, b, and c are replicated; objects d and e are stubbed; objects f and g are ignored.

Figure 3.1   Two-level Fault of an Object

---

Faulting in Response to a Message

When object e, which is a stub, receives a message, it faults in a replicate of its counterpart GemStone server object.

A stub faults in a replicate in response to a message. Therefore, direct references to instance variables can cause problems. Direct access is not a message-send; the stub will not fault in its replicate, because it receives no message; neither can it supply the requested value. To avoid this problem, use accessor methods to get or set instance variables.

The following sequence demonstrates the problem. The object starts as a replicate in client Smalltalk:

demonstrateProblem

| firstTemp secondTemp |

firstTemp := size.  "Size is an inst var of the receiver. 

FirstTemp now has a valid value."

self stubYourself.  "self is now a stub, and has no

				instance variable values"

secondTemp := size. "Since this access is not a message 

				send, it does not unstub self.

				SecondTemp now contains an invalid

				value, most likely nil."

^Array with: firstTemp with: secondTemp.

Using an accessor method, on the other hand, causes the stub to be faulted in and yields the correct result:

self size. "This is a message, and faults the stub."

e is now a replicate, as shown in Figure 3.2. The new replicate responds to the message.

Figure 3.2   A Stub Responds to a Message

---

Faulting in Changes From Other Sessions

Now, suppose another session commits a change to b?

Each session maintains its own view of the GemStone object server’s shared object repository. The session’s private view can be changed by the client application when it adds, removes, or modifies objects—that is, you can see your own changes to the repository—or the Gem can change your view at transaction boundaries or after a session has executed GemStone Smalltalk.

A Gem maintains a list of repository objects that have changed and notifies GemBuilder of any changes to objects it has replicated. If it finds any changed counterparts, it updates the client object with the new GemStone value.

The way in which these changes depends on the server product, and with 32-Bit GemStone/S, on a GemBuilder configuration setting.

Overriding Defaults

Because linked sessions may be able to access the gem with lower latency, GemBuilder ships with faultLevelLnk set to 2 and faultLevelRpc set to 4. In this way, linked sessions replicate less at login, faulting in objects as they are needed.

• You can override these defaults for specific instance variables of specific replicates.
• You can also stub or replicate certain objects explicitly.

To specify fault levels for all instance variables, implement a class method replicationSpec for the client class. Replication specifications are versatile mechanisms described starting here.

To cause a replicate to become a stub, send it the message stubYourself. This can be useful for controlling the amount of memory required by the client Smalltalk image. Explicit control of stubs is discussed in Optimizing Space Management.

Sometimes stubbing is not desirable, either for performance reasons or for correctness. For example, primitives cannot accept stubs as arguments if the primitive accesses the instance variables of the argument. If your application uses an object as an argument to a primitive, you must either prevent that object from ever becoming a stub, or ensure that it is replicated before the primitive is executed.

To cause a stub to become a replicate, send it the message fault. Stubs respond to this message by replicating; replicates return self. The message faultToLevel: allows you to fault in several levels at once, as specified.

Defunct Stubs

Faulting in a stub relies on the existence of a valid GemStone server object to replicate or forward to. If an object is stubbed and the session logs out, a message to that stub raises an error complaining that it is defunct. For example, suppose MyGlobal is modified in a 32-bit server, thereby stubbing it in your client session. If the session logs out before MyGlobal is faulted back in, the client Smalltalk dictionary contains a defunct stub.

Because GemBuilder cannot safely assume that a given object will retain the same object identifier from one session to the next, it cannot simply fix the problem at next login. That’s the job of a connector: to reestablish at login the stub’s relationship to GemStone. A connector can do so either directly, by connecting the stub itself, or transitively, by connecting some object that refers to the stub.

If you’ve defined a connector for MyGlobal, logging back into GemStone reconnects it.

Now, suppose an instance variable of MyGlobal becomes a stub shortly before a session logs out. Sending a message to this variable will produce a defunct stub error. At next login, MyGlobal’s connector will fault in the variable. You can then retry the message, but only by means of a message sent to MyGlobal (or another connected object). If the application is maintaining a direct reference to the previous defunct stub, the error will persist.

NOTE
You cannot proceed from a defunct stub error. After you’ve encountered this error, determined the cause, and corrected the problem, you must restart the client Smalltalk operation that encountered the defunct stub.

Replication Specifications and Class Versions

As explained in Mapping and Class Versions, client Smalltalk classes connect not simply to GemStone Smalltalk classes, but to specific server class versions. A class connector connects to only one server class version.

A replication spec, therefore, affects only client instances connected to instances of the correct GemStone class version.

Suppose, for example, that you define and redefine class X in the server until its class history lists three versions. Your client Smalltalk class is connected to Version 2. Class X’s replication spec will affect server instances of Class X, Version 2. If the server contains instances of Class X, Versions 1 or  3, the replication spec will not affect them.

Multiple Replication Specifications

It’s not always possible to define one replication spec that works well for all operations in an application. Some queries or windows may require a different object profile than others in the same application and session; a replication spec crafted to optimize one set of operations can make others inefficient.

By default, the message replicationSpec returns the default replication spec. Change this by sending the message replicationSpecSet: #someRepSpecSelector to an instance of GbsSession. The selector of the replicationSpec acts as the named of the replication spec. Using this message to specify the replicationSpec to use to perform a particular operation, you can specify multiple replication specs, selecting one dynamically according to circumstances. The following procedure shows how:

Step 1. Decide on a new name, such as replicationSpec2.

Step 2. Implement Object class >> replicationSpec2 to return self replicationSpec.

Step 3. Reimplement replicationSpec2 as appropriate in those application classes that need it.

Step 4. Immediately before your application performs the query or screen fetch or other operation that requires the second replication spec, send replicationSpecSet: #replicationSpec2 to the current GbsSession instance, specifying the selector symbol of the new replicationSpec method.

Step 5. Immediately after the operation completes, send replicationSpecSet: #replicationSpec to the GbsSession to restore replication. If the session could be addressed from more than one client Smalltalk process, your application should use a semaphore to control access to the session.

For example, suppose your application has a class Employee, with instance variables firstName, lastName, and address. address contains an instance of class Address. The application has one screen that displays the names from a list of employees, and another screen that displays the zip codes from a list of employee addresses. Here’s how to replicate only what’s needed:

Step 1. Define a new replication spec with the selector empNamesRepSpec.

Step 2. Implement Object class >> empNamesRepSpec as:

^self replicationSpec. 

Step 3. Implement Employee class >> empNamesRepSpec as:

^#((firstName min 1) (lastName min 1) (address stub)) 

Step 4. Define another replication spec with the selector empZipcodeRepSpec.

Step 5. Implement Object class >> empZipcodeRepSpec as:

^self replicationSpec 

Step 6. Define Employee class >> empZipcodeRepSpec as:

^#((firstName stub) (lastName stub) (address min 2)) 

and Address class >> empZipcodeRepSpec as:

^#((city stub) (state stub) (zip min 1)) 

Step 7. Before opening the employee names screen, send:

myGbsSession replicationSpecSet: #empNamesRepSpec

Restore it to #replicationSpec after opening the window.

Step 8. Before opening the zip code window, send:

myGbsSession replicationSpecSet: #empZipcodeRepSpec

Restore it to #replicationSpec after opening the window.

For each window, the procedure above reduces the number of objects retrieved to the minimum required. Other objects fault in as stubs; if subsequent input requires them, they are retrieved transparently.

Managing Interobject Dependencies

Replication specs are ordinarily an optimization mechanism. Some applications, however, require a replication spec to function correctly. If the structural initialization of an object depends on other objects, you must implement replication specs to ensure that, when GemBuilder replicates an object, it also replicates those objects it depends on.

Hashed collection classes that wish to replicate instances between client and server should answer true to the message #gbsMustDeferElements. This is the recommended approach.

When an object whose class answers true to #gbsMustDeferElements is faulted to the client, the elements are not added to the collection until the replication of those elements is complete. This ensures that all of the information necessary to compute the hash of the element is present before adding it to the collection; if added earlier, its hash might change as its replication continued, corrupting the collection.

There is one exception to this requirement. Hashed collections that compute hash purely on the identity hash of their elements may answer false to #gbsMustDeferElements, since their hash values are computed strictly on the identity of the elements themselves, which is always present.

NOTE
If you do not use #gbsMustDeferElements (the recommended approach), you must independently address the issues described in the following paragraphs.

For example, in order to create a Dictionary when replicating it from the server, we need to be able to send hash to each key to determine its location in the hash table (hash values aren’t necessarily the same in the server as they are in the client). So, if GemStone replicates a Dictionary, it must also at a minimum replicate the association and the key in the association, so it can compute the hash. The default implementation for Dictionary class >> replicationSpec therefore contains #(indexable_part min 1), and Association class >> replicationSpec contains #(key min 1).

This works for Dictionaries with simple keys such as strings, symbols or integers. If an application has dictionaries with complex keys, though, additional replication specs can be required. For example, if you are storing Employees as keys in a dictionary, and you’ve implemented = and hash in Employee to consider the firstName and lastName, then you must ensure that when a dictionary containing Employees is traversed, so are the associations, the employees, and the firstName and lastName.

You could ensure this by implementing Employee class >> replicationSpec to include #(firstName min 1) and #(lastName min 1). Or, if you had a special Dictionary class for Employees, you could include #(indexable_part min 3) in that dictionary class’s replication spec. However, this could cause the entire Employee to be replicated whenever one of these dictionaries is replicated, rather than just the firstName and lastName.

We recommend that you use the default replication spec #replicationSpec as the base replication spec for all classes to reflect interobject dependencies. When defining other replication specs, make sure the default implementation in Object is:

^self replicationSpec

Ensure that subclass implementations of the new replicationSpec method do not stray from the default, so as not to break interobject dependencies.

Precedence of Multiple Replication Specs

It’s possible to implement replication specs that appear to contradict each other. Such apparent conflicts are resolved deterministically according to the order in which instance variables appear in a replication spec and the order in which objects are replicated. If a superclass specifies one way of handling an instance variable, and a subclass reimplements replicationSpec to handle the same variable in a different way, the last occurrence takes precedence.

For example, suppose the value returned from sending replicationSpec to the subclass is:

#((name min 1) (name max 2))

The last occurrence of the instance variable is max 2, and therefore takes precedence.

If subclass implementations of replicationSpec always append their results to super replicationSpec, the subclass will reliably override the superclass handling of a given instance variable. The recommended approach is:

^super replicationSpec, #((name max 2))

not:

^#((name max 2)), super replicationSpec.

Another apparent contradiction can arise between parent and child objects. For example, suppose Employee refers to an Address, which refers to a complex object County. The Employee replicationSpec includes #(address min 5), specifying that several levels of the County object are to be replicated. But if Address includes #(county max 1), it modifies Employee’s handling of address.

Employee specifies, “Get at least 5 levels of address.” Address specifies, “Whatever you do, don’t get more than one level of county.” The apparent contradiction is resolved by the order in which these specifications are encountered: because Address is encountered after Employee, Address takes precedence.

If your object network includes cycles, different replication specs could take effect at different times, depending on which object is the replication root at any given time. Given a specific root object, however, it’s always possible to determine the exact effect of a set of replication specs.

Example 3.1 

PositionableStream>>namedValues

	| aClone |

	aClone := self copy.

	aClone instVarAt: 1 put: self contents.

	aClone instVarAt: 2 put: position + 1.

	^aClone

An alternative might return an instance of GbsBuffer (a subclass of Array) of the appropriate size. (A special buffer class is necessary to distinguish between trying to store an array and trying to store the named values of an object residing in a buffer.)

The default implementation of namedValues is to return self. In this case, the instance variables are processed directly from the object being stored, eliminating the need for a temporary array.

Implementations of indexableValues must return an indexable collection containing a sequential list of the elements in the collection. In Example 3.2, for class Set, an Array is returned, because the indexable fields of a Smalltalk set are a sparse list of the actual elements.

Example 3.2 

Set>>indexableValues

	| values index |

	values := Array new: self size.

	index := 1.

	self elementsDo: [:each |

		values at: index put: each.

		index := index + 1].

	^values

The default implementation of indexableValues is to return self. In this case, the indexable slots are processed directly from the object being stored, eliminating the need for a temporary array.

You can also override the messages indexableValueAt: and namedValueAt: to return processed values rather than the actual values in the indexable and named slots of the object. For example, OrderedCollection might implement indexableValueAt: as:

OrderedCollection>indexableValueAt: index

	^self at: index

This lets OrderedCollection control for the fact that its underlying indexable slots are being managed by the firstIndex and lastIndex instance variables—that is, the first actual indexable slot of the object may not necessarily be the first logical element.

In conjunction with these two methods, you might need to reimplement the messages indexableSize and namedSize as well. For example, to match the implementation of indexableValueAt:above, OrderedCollection would have to implement indexableSize as shown below; otherwise, the object storage mechanisms would try to iterate over the entire list of indexable slots rather than those controlled by firstIndex and lastIndex:

indexableSize

	^self size

Image-stripping Limitations

Block replication relies on the client Smalltalk compiler and decompiler; if they’ve been removed from a deployed runtime environment, blocks cannot be replicated.

Two workarounds are possible:

1. Leave the compiler and decompiler in the image. For example, the VisualWorks Image Maker tool offers a “Remove Compiler” option which you can deselect to leave the compiler and decompiler in the image.

2. Do not use block replication. Usually this requires implementing a cover method for the block in a GemStone method, and sending that message instead. For instance:

aForwarder select: [ :name | name = #Fred ]

is instead coded:

aForwarder selectNameEquals: #Fred

...and in GemStone, selectNameEquals: is implemented as:

selectNameEquals: aName

		^self select: [ :name | name = aName ]

When the block is encoded entirely in GemStone in this way, you can further optimize its operation by taking advantage of indexes and use an optimized selection block, as described in the GemStone Programming Guide.

Temporary Variable Reference Restrictions

A block is replicated in the form of its source code, without its surrounding context. Therefore, values drawn from outside the block’s own scope cannot be relied upon to exist in both the client Smalltalk and in GemStone. Replication is not supported for blocks that reference instance variables, class variables, method arguments, or temporary variables declared external to the block’s scope.

An exception is allowed in the case of global references, such as class names:

• Global variable references from inside a block must have the same name in both object spaces.

In the case of global variables containing data, it is the programmer’s responsibility to ensure that the global identifier represents compatible values in both contexts.

Temporary variable reference restrictions disallow the following, because “tempName” is declared outside the block’s scope:

| namedEmps tempName |

tempName := 'Fred'.

namedEmps := myEmployees select:

	[ :anEmployee | (anEmployee name) = tempName ].

As a workaround, implement a new Employees method in GemStone Smalltalk named select:with: that evaluates a two-argument block, in which the extra block argument is passed in as the with: parameter. For example:

select: aBlock with: extraArg

|result|

result := self speciesForSelect new.

self keysAndValuesDo: [ :aKey :aValue |

   (aBlock value: aValue value: extraArg)

      ifTrue: [result at: aKey put: aValue]

].

^ result.

You can then rewrite the application code to pass its temporary as the argument to the with: parameter without violating the scope of the block:

| namedEmps tempName |

tempName := 'Fred'.

namedEmps := myEmployees 

	select: 	[:anEmployee :extraArg | 

			(anEmployee name) = extraArg		] 

	with: tempName.

Restriction on References to self or super

References to self and super are also context-sensitive and, therefore, disallowed:

• A replicated block cannot contain references to self or super.

For example, the following code cannot be forwarded to GemStone because the parameter block contains a reference to self:

myDict at:#key ifAbsent:[ self ]

References to self or super in forwarded code must occur outside the scope of the replicated block, where you can be sure of the context within which they occur. For example, you can rewrite the above code to return a result code, which can then be evaluated in the calling context, outside the scope of the replicated block:

result := myDict at:#key ifAbsent:[#absent].

result = #absent ifTrue: [ self ]

Explicit Return Restriction

Because a block is replicated without its surrounding context, a return statement has no surrounding context to which to return. Therefore:

• A replicated block cannot contain an explicit return.

For example:

result := myDict at:#key ifAbsent:[ ^nil ]

is disallowed. The statement can be recoded to perform its return within the calling context:

result := myDict at:#key ifAbsent:[#absent].

result = #absent ifTrue: [ ^nil ]

Replicating GemStone Blocks in Client Smalltalk

Also supported, though less commonly used, is the replication of GemStone blocks in client Smalltalk. Similar restrictions apply with regard to external references and the need for compiler/decompiler support. Blocks most frequently passed from the server to the client are the sort blocks that accompany instances of SortedCollection and its subclasses. Sort blocks rarely have occasion to violate replicated block restrictions.

If restrictions hamper you, consider using block callbacks instead.