GemStone compatibility and development rules

Use the live system

All GT / GemStone code related operations should be performed on the live system using available tools (via the gtoolkit mcp server). git repositories should only be inspected / modified for shell scripts, topaz files or if specifically required.

Code Management

All code is managed from within GT, any time a method is to be added or modified it should be done in GT and then updated in GemStone.

Method protocols

When modifying an existing method, check what it's protocol is, and unless it is 'as yet unclassified', DO NOT CHANGE THE PROTOCOL unless explicitly requested. This is particularly important for EXTENSION METHODS (where the protocol begins with a '*'). If you feel the need to change a protocol, stop and ask for confirmation

Class and class-instance variables

GemStone will commit the value of class and class-instance variables to the database. In general, this is not what is desired when porting code. In particular, class methods that answer a default, instance or uniqueInstance that store the instance in a class or class-instance variable should not store the value in the database. In these cases they should be added to SessionTemps with a name based on the class and accessor method, e.g. SessionTemps current at: #Class_selector_value ifAbsentPut: [ self new ].

GemStone specific code

There are many differences between GT and GemStone classes. Where GemStone requires an alternate implementation there are a few different potential solutions:

gsCode:

Adding a pragma with the <gsCode: gemstoneSourceString> pragma to the method will result in the gemstoneSourceString being used when the code is exported (see GtGemStoneGtCodeExporter Object << #GtGemStoneGtCodeExporter slots: { #exporter }; tag: 'Export'; package: 'GToolkit-GemStone-Pharo' ). An example is GtGemStoneTopazExporterExamples>>#gsCodeExampleMethod gsCodeExampleMethod "Provide an example method with the gsCode: pragma" <gsCode: '^ self copyFrom: 1 to: 3'> ^ self first: 3 . NOTE: the gemstoneSourceString replaces everything below the pragma, meaning that the method signature doesn't need to be included, so in the example linked above the method signature and comment will be part of the generated GemStone code.

Note that the method's class must be included in the GtGemStoneGtCodeExporter>>#gsCodeClasses gsCodeClasses | names | names := OrderedCollection new. (Pragma allNamed: #gsCodeClasses in: self class) do: [ :pragma | (self perform: pragma methodSelector) do: [ :name | names addIfNotPresent: name ] ]. ^ names asArray collect: [ :each | Smalltalk globals at: each ifAbsent: [ nil ] ] thenReject: [ :each | each isNil ] list.

This can only be used in methods owned by feenkcom, i.e. CompiledMethod>>#hasFeenkRepositoryAvailable hasFeenkRepositoryAvailable ^ self isInAvailableGitRepositoryOwnedBy: 'feenkcom' answers true.

GtGemStoneExtensionMethod

Extension methods can be added to GemStone with the code managed by GT by using GtGemStoneExtensionMethod Object << #GtGemStoneExtensionMethod slots: { #selector . #protocol . #source . #meta . #gtVersions . #className . #hash }; package: 'GToolkit-GemStone' and GtGemStoneExtensionMethods Object << #GtGemStoneExtensionMethods slots: {}; package: 'GToolkit-GemStone' , see their class comments for further information.

This is generally preferred for Pharo methods that aren't managed by GT, e.g. Collection>>#intersection: intersection: aCollection "Answer the set theoretic intersection of two collections." "(#(1 2 3 4) intersection: #(3 4 5)) >>> #(3 4)" "(#(1 2 3 4) intersection: #()) >>> #()" "(#() intersection: #(1 2 3 4)) >>> #()" "('hello' intersection: 'world') >>> 'ol'" ^ self species withAll: (self asSet intersection: aCollection) asArray , and where the class otherwise isn't exported.

gtDo:gemstoneDo:

For methods that are largely the same in both GT and GemStone, Object>>#gtDo:gemstoneDo: gtDo: gtoolkitBlock gemstoneDo: gemstoneBlock "Evaluate the supplied platform specific block" ^ gtoolkitBlock value provides a way to have a small section of code be platform specific. An example use is in BlockClosureOnProcessExamples>>#getCallStack getCallStack <gtExample> <return: #SmallInteger> | result | result := [ 1 / 0 ] on: ZeroDivide withProcessDo: [ :exception :process | self gtDo: [ exception stackString ] gemstoneDo: [ process stackReportToLevel: 100 withArgsAndTemps: true andMethods: true includeSource: false. ] ]. self assert: result size > 500. ^ result .

When choosing between gsCode: and gtDo:gemstoneDo:, gsCode: is normally used when the method body is significantly different between GT and GemStone.

The following are a number of commonly encountered issues when getting GT code working in GemStone:

new doesn't call initialize

In GemStone, new, and its variants, don't call initialize. Unless the GT version also defines new, or one of its variants, this will be resolved by adding a GtGemStoneExtensionMethod Object << #GtGemStoneExtensionMethod slots: { #selector . #protocol . #source . #meta . #gtVersions . #className . #hash }; package: 'GToolkit-GemStone' method.

When debugging code being ported from GT to GemStone, if an existing method appears to not initialise instance variables, first check that the initialize method is being called prior to adding lazy initialisation to the ported method.

Class / method reflect

Navigating the class / method structure in GemStone is often much slower than in GT. Instead of requesting classes directly, lookups such as superclasses, subclasses, references, etc. should be made through the ClassOrganizer gtDefault instance.

Missing methods

The following list of methods that exist in GT, but are missing in GemStone and have equivalents in GemStone that are considered close enough for now. The list is formatted originalMethod -> replacementMethod: 'canPerform: aSelector' -> 'canUnderstand: aSelector' 'includesSubstring: aString' -> 'findPattern: { aString} startingAt: 1' 'includesSubstring: aString caseSensitive: false' -> 'findPatternNoCase: { aString } startingAt: 1'

Method references

When responding, GT method references are normally styled using the gtMethod: attribute. As GemStone methods often don't exist in the GT image, they should be styled using the normal code styling, i.e. back-ticks (`).