2. Interacting with GemBuilder

Prepare for Login

Before you can login, you need a running GemStone repository Stone and, usually, a NetLDI process. Setting up the repository and NetLDI, the options for RPC vs. linked logins, and the login parameters to login a Gem session process for either kind of login, is described in the System Administration Guide for GemStone/S 64 Bit.

While linked logins may have performance advantages under some circumstances, RPC logins have advantages, and are required when the application is on a different node than the Stone, and RPC logins avoid the risk of invalid memory references causing repository corruption. While performing development and debugging you should log in RPC, to avoid the risk of repository corruption. This discussion will primarily describe the process for RPC logins.

As described in the System Administration Guide for GemStone/S 64 Bit, you will need to determine the following:

• Network Resource Syntax (NRS) for the Stone. By default, this is gs64stone.
• NRS for the Gem. This is not set for a linked login, and may be ’gemnetobject’ for a local RPC login.
• Authentication information for the Stone (GemStone userId and password).
• Authentication information for the NetLDI (UNIX username and password). This is not required if the NetLDI is running in guest mode.

Logging In and Out

The functions GciInitAppName and GciInit initialize GemBuilder. When it is used, your application should call GciInitAppName before calling GciInit. Your C application must not call any GemBuilder functions other than this until it calls GciInit.

The GciSetNet or GciSetNetEx functions set the values for the Stone and Gem NRS, and NetLDI authentication information if required.

Then, to do any useful repository work, you must create a session with the GemStone system by calling GciLogin, GciLoginEx, or GciNbLoginEx; these functions have arguments for providing the GemStone username and password.

The *Ex variants support encrypting passwords before passing these from the GCI application to the Gem, which is useful if you are operating over an unsecure network. Encryption is done using the GciEncrypt function.

If your application calls GciLogin again after you are already logged in, GemBuilder will create an additional, independent, GemStone session for you. Multiple sessions can be attached to the same GemStone repository, or they can be attached to different repositories. The maximum number of sessions that may be logged in at one time depends upon your version of GemStone and the terms of your license agreement.

From the point of view of GemBuilder’s classic API, only a single session is active at any one time. It is known as the current session. Any time you execute code that communicates with the repository, it talks to the current session only. Other sessions are unaffected.

Each session is assigned a number by GemBuilder as it is created. Your application can call GciGetSessionId to inquire about the number of the current session, or GciSetSessionId to make another session the current one. The GemBuilder for C functions operate on the current session, and if you login multiple sessions, your application is responsible for treating each session distinctly.

An application can terminate a session by calling GciLogout. After that call returns, the current session no longer exists.

Transaction Management

System abortTransaction.

// set aSession in manual transaction mode

GciExecuteStr("System transactionMode: #manualBegin", OOP_NIL);

// set aSession in automatic transaction mode

GciExecuteStr("System transactionMode: #autoBegin", OOP_NIL);

GemStone-Defined Object Macros

The GemBuilder include file gcioop.ht defines macros for a number of frequently-used objects, such as the GemStone objects nil, true, and false, and kernel classes in the GemStone repository.

In addition, it defines OOP_ILLEGAL. This represents a value that will never be used to represent any object in the repository. You can thus initialize the state of an OOP variable to OOP_ILLEGAL, and test later in your program to see if that variable contains valid information.

GemStone Object Implementation Types

Objects in GemStone can be divided up into four different types, based on the internal implementation. These are handled and structure internally differently, and handled differently by some GemBuilder functions. These types are Special, Byte, Pointer, and NSC.

More detail is provided in the GemStone Programming Guide.

GemStone Data Types

When moving data between GemStone and your C application, the GemStone object representation must be converted to structures consisting of C data types.

For basic data types such as integers, floating points, and strings, you must convert between the OOP representation in GemStone and the basic C data type.

GemBuilder provides a number of functions that allow you to test for the type of data and perform conversion. These are listed in Functions and Macros for Testing and Converting Objects and Values.

In Example 2.1, assume that you have defined a Smalltalk class called Address that represents a mailing address. If the class has five instance variables, the OOPs of one instance of Address can be imported into a C array called address. Assume that the fifth instance variable represents the zip code of the address.

The fifth element of address is the OOP of the SmallInteger object that represents the zip code, not the zip code itself. Example 2.1 imports the value of the zip code object to the C variable zip.

int64 example_zipcode(OopType addressId)

{

  // returns the zipcode or -1 if an error occurred, 

  enum { addr_num_instVars = 5 };

  OopType instVars[addr_num_instVars];

  int numRet = GciFetchOops(addressId, 1, instVars, addr_num_instVars);

  if (numRet != (int)addr_num_instVars)

    return -1;

  BoolType conversionError = FALSE;

  int64 zip = GciOopToI64_(instVars[4], &conversionError);

  if (! conversionError)

    return -1;

  // zip now contains an integer that has the same

  //  value as the GemStone object represented by address[4] 

  return zip;

}

Object Creation

The following GemBuilder functions allow your C program to create one or more new instances of one or more Smalltalk classes:

GciNewOop

GciNewOops

GciNewOopUsingObjRep

Once your application has created a new object, it can export the object to the repository by making sure some committed object in the repository references the new object. For example, add the object to a collection, or set the value of an instance variable in an existing object. This can be done with a call to one of the GciStore... functions.

Your C application may also create a new object by executing Smalltalk code, and create the reference from a persistent object in Smalltalk code.

Once the new object is created and the reference is committed, the object has been exported to the repository.

Executing Smalltalk Code in GemStone

Your C application can perform Smalltalk code execution using the GemBuilder functions since as GciExecute*and GciExecuteStr*.

The Smalltalk code may be a message expression, a statement, or a series of statements; any self-contained section of code that you could, for example, execute within a Topaz run command. The code can be in a GemStone string object and executed using a GciExecute function, or a C string and performed using a GciExecuteStr function.

These functions expect a SymboList, which is used to bind any symbols contained in the Smalltalk source. If the symbol list is OOP_NIL, GemStone uses the symbol list associated with the currently logged-in user.

Example 2.2 demonstrates the use of GciExecuteStr.

OopType example_execute(void)

{

  // Pass the String to GemStone for compilation and execution. 

  // If it succeeds, return the result of the expression 

  // otherwise OOP_NIL will be returned.

   OopType result = GciExecuteStr("Globals keys size", OOP_NIL);

   return result; 

}

Sending Messages to GemStone Objects

To send a message to a GemStone object, use GciPerform or one of its variants. GciPerform takes a object, a selector, and arguments; when GemStone receives this, it invokes and executes the method associated with that message.

Code execution occurs in the repository server, not in the application.

The following example shows two statements, one using GsExecuteStr and the other using GsPerform.

void example_messageSends(void)

{

   OopType userGlobals = GciResolveSymbol("UserGlobals", OOP_NIL);

   OopType aKey = GciNewSymbol("myNumber"); 

   OopType aValue = GciI32ToOop(55);

   OopType argList[2];

   argList[0] = aKey;

   argList[1] = aValue;

  // both the following have the same effect 

   GciExecuteStr("UserGlobals at: #myNumber put: 55", OOP_NIL);

   GciPerform(userGlobals, "at:put:", argList, 2);

}

Interrupting GemStone Execution

You can interrupt GemBuilder execution in two different ways:

• GciSoftBreak sends a soft break, which interrupts the Smalltalk virtual machine only. The GemBuilder functions that can recognize a soft break are GciPerform, GciContinue, GciExecute, GciExecuteFromContext, GciExecuteStr, and GciExecuteStrFromContext.
• GciHardBreak sends a hard break, which interrupts the Gem process itself, and is not trappable through Smalltalk exception handlers.

Issuing a soft break may be desirable if, for example, your application is executing code in Smalltalk, and enters an infinite loop.

In order for GemBuilder functions in your program to recognize interrupts, your program usually needs a signal handler that can call the functions GciSoftBreak and GciHardBreak. Since GemBuilder generally does not relinquish control to an application until it has finished its processing, soft and hard breaks are then initiated from an interrupt service routine. Alternatively, if you are calling the non-blocking GemBuilder functions, you can service interrupts directly within your event loop, while awaiting the completion of a function.

If GemStone is executing when it receives the break, it replies with an error message. If it is not executing, it ignores the break.

Direct Access to Metadata

Your C program can use GemBuilder’s structural access functions to request certain data about an object:

• Class

Each object is an instance of some class. The class defines the behavior of its instances. To find an object’s class, call GciFetchClass.

• Format

GemStone represents the state of an object in one of four different implementations (formats): byte, pointer, NSC (non-sequence able collection), or special, specified as GC_FORMAT_OOP, GC_FORMAT_BYTE, GC_FORMAT_NSC, and GC_FORMAT_SPECIAL. Data types are described under GemStone Object Implementation Types. To find an object’s implementation, call GciFetchObjImpl.

• Size

The function GciFetchNamedSize returns the number of named instance variables in an object, while GciFetchVaryingSize_ returns the number of unnamed instance variables. GciFetchSize_ returns the object’s complete size (the sum of its named and unnamed variables).

The result of GciFetchSize_ depends on the object’s implementation format. For byte objects (such as instances of String or Float), GciFetchSize_ returns the number of bytes in the object’s representation. For pointer and NSC objects, this function returns the number of OOPs that represent the object. For “special” objects (Special), the size is always 0.

void example_fetchBytes(OopType aGsString)

{

   char supplierName[1025];

   int64 size = GciFetchBytes_(aGsString, 1, (ByteType*)supplierName, 

		sizeof(supplierName) - 1);

   supplierName[size] = '\0';

   // supplierName now contains the bytes of the GemStone object 

   // aGsString, or the first 1024 bytes. 

}

void example_fetchOops(OopType currSup)

{

  enum { num_ivs = 7 };

  OopType instVars[num_ivs];

  int numRet = GciFetchNamedOops(currSup, 1L, instVars, num_ivs);

  if (numRet == 7) {

    // instVars now contains the OOPs of the seven instance

    // variables of the GemStone object referenced by currSup

  } else {

    // error occurred or currSup is not of expected class or size

  }

}

Efficient Fetching and Storing with Object Traversal

The functions described in the preceding sections allow your C program to import and export the components of a single GemStone object. When your application needs to obtain information about multiple objects in the repository, it can minimize the number of network calls by using GemBuilder’s object traversal functions.

Suppose, for example, that you had created a GemStone Employee class like the one in Example 2.6.

 Object subclass: 'Employee'

    instVarNames: #( 'name' 'empNum' 'jobTitle'

                     'department' 'address' 'favoriteTune')

    classVars: #()

    classInstVars: #()

    poolDictionaries: #()

    inDictionary: UserGlobals

How Object Traversal Works

To understand the object traversal mechanism, think of each GemStone pointer object as the root of a tree (for now, ignore the possibility of objects containing themselves). The branches at the first level go to the object’s instance variables, which in turn are connected to their own instance variables, and so on.

Figure 2.1 illustrates a piece of the tree formed by an instance of Employee.

Figure 2.1   Object Traversal and Paths

---

In a single call, GemStone’s internal object traversal function walks such a tree post-depth-first to some specified level, building up a “traversal buffer” that is an array of “object reports” describing the classes of the objects encountered and the values of their contents. It then returns that traversal buffer to your application for selective extraction and processing of the contents.

Thus, to make your list of job titles and favorite tunes with the smallest possible amount of network traffic per employee processed, you could ask GemStone to traverse each employee to two levels (the first level is the Employee object itself and the second level is that object’s instance variables). You could then pick out the object reports describing jobTitle and favoriteTune, and extract the values stored by those reports (welder and Am I Blue respectively).

This approach would minimize network traffic to a single round trip.

One further optimization is possible: instead of fetching each employee and traversing it individually to level two, you could ask GemStone to begin traversal at the collection of employees and to descend three levels. That way, you would get information about the whole collection of employees with just a single call over the network.

Efficient Fetching And Storing with Path Access

As you’ve seen, object traversal is a powerful tool for fetching information about multiple objects efficiently. But writing the code for parsing traversal buffers and object reports may not always be simple. And even if you can afford the memory for importing unwanted information, the processing time spent in parsing that information into object reports may be unacceptable.

Consider the Employee object illustrated in the Figure 2.1. If your job were to extract a list of job titles and favorite tunes from a set of such Employees, it would be reasonable to use GemBuilder’s object traversal functions (as described above) to get the needed information. The time spent in building up object reports for the unwanted portions would probably be negligible. Suppose, however, that there were an additional 200 instance variables in each Employee. Then the time used in processing wasted object reports would far exceed the time spent in useful work.

Therefore, GemBuilder provides a set of path access functions that can fetch or store multiple objects at selected positions in an object tree with a single call across the network, bringing only the desired information back. The function GciFetchPaths lets you fetch selected components from a large set of objects with only a single network round trip. Similarly, your program can call GciStorePaths to store new values into disparate locations within a large number of GemStone objects.

Signal Handling in Your GemBuilder Application

Under UNIX, it is important that signals be enabled when your code calls GemBuilder functions. Disabling signals has the effect of disabling much of the error handling within GemBuilder. Because signal handlers can execute at arbitrary points during execution of your application, your signal handling code should not call any GemBuilder functions other than GciSoftBreak, GciHardBreak, or GciCallInProgress.

GciInit always installs a signal handler for SIGIO. This handler chains to any previous handler. Do not, under any circumstances, turn off SIGIO.

In the linkable (GciLnk) configuration, GciInit also does the following:

• Installs handlers to service and ignore these signals (if no previous handler is found): SIGPIPE, SIGHUP, SIGDANGER
• Installs handlers to treat the following signals as fatal errors if they are defined by the operating system: SIGTERM, SIGXCPU, SIGABRT, SIGXFSZ, SIGXCPU, SIGEMT, SIGLOST
• Installs a handler for SIGUSR1. If you have a valid linkable session, SIGUSR1 will cause the Smalltalk interpreter to print the current Smalltalk stack to stdout or to the Topaz output file. This handler chains to any previous handler.
• Installs a handler for SIGUSR2, which is used internally by a Gemstone session. This handler chains to any previous handler.
• Installs a handler to gracefully handle SIGCHLD if no previous handler is found.
• Installs a handler to treat SIGFPE as a fatal error if no previous handler is found.
• Installs handlers for SIGSEGV, SIGILL and SIGBUS. If the program counter is found to be in libgci*.so code, or if no previous handler is available to chain to, these are fatal errors.

If your application installs a handler for SIGIO after calling GciInit, your handler must chain to the previously existing handler.

If your application uses Linkable GCI and installs any signal handlers after calling GciInit, you must chain to the previously existing handlers. If you install handlers for SIGSEGV, SIGILL or SIGBUS, your handler must determine if the program counter at the point of the signal is in your own C or C++ code and if not, must chain to the previously existing handler. You must only treat these signals as fatal if the program counter is in your own code.

SIGVTALRM is used by the ProfMonitor class. Similar chaining is required for SIGVTALRM if you intend to use ProfMonitor.

If you are linking with other shared libraries, it is recommended that GciInit be called after all other libraries are loaded.

Executing Host File Access Methods

If you use any of the GciPerform* or GciExecute* functions to execute a Smalltalk host file access method (as listed below), and you do not supply a full file pathname as part of the method argument, the default directory for the Smalltalk method depends on if you are running linked or RPC GemBuilder.

With GciLnk, the default directory is the directory in which the Gem (GemStone session) process was started. With GciRpc, the default directory is the home directory of the host user account, or the #dir specification of the network resource string.

The Smalltalk methods that are affected include System class>>performOnServer: and the file accessing methods implemented in GsFile. See the file I/O information in the Programming Guide.

Writing Portable Code

If you want to produce code that can run in both 32-bit and 64-bit environments, observe the following guidelines:

• Don’t hard-code size computations. Instead, use sizeof operations, so that if some structure changes, your code will still return the correct values.
• If you are using printf strings to print 64-bit integers, you might find it convenient to use the FMT_* macros in $GEMSTONE/include/gci.ht. Those macros help you to compose a format string for a printf that will be portable. In particular, use of the FMT_ macros make the printing of 64-bit integers portable between Windows and UNIX. These macros are recommended:

OopType – FMT_OID 

int64 – FMT_I64

uint64 – FMT_U64

intptr_t – FMT_PTR_T

uintptr_t – FMT_UPTR_T

• To avoid discrepancies between 32-bit and 64-bit environments, avoid the use of long or unsigned long in your code. Instead, you can use the type intptr_t, which makes the variable the same size as a pointer, regardless whether your application is running in 32-bit or 64-bit. Alternatively, you can use int64 or int to fix the size of the variable explicitly.

Polling for Errors

Each call to GemBuilder can potentially fail for a number of reasons. Your program can call GciErr to determine whether the previous GemBuilder call resulted in an error. If so, GciErr will obtain full information about the error. If an error occurs while Smalltalk code is executing (in response to GciPerform or one of the GciExecute... functions), your program may be able to continue Smalltalk execution by calling GciContinue.

If you are in a UserAction and want to pass the error back to the Smalltalk client, you must execute GciRaiseException.

Error Jump Buffers

When your program makes three or more GemBuilder calls in sequence, jump buffers provide significantly faster performance than polling for errors.

When your C program calls Gci_SETJMP, the context of the current C environment is saved in a jump buffer designated by your program. GemBuilder maintains a stack of up to 20 error jump buffers. A buffer is pushed onto the stack when GciPushErrJump is called, and popped when GciPopErrJump is called. When an error occurs during a GemBuilder call, the GemBuilder implementation calls GciLongJmp using the buffer currently at the top of GemBuilder’s error jump stack, and pops that buffer from the stack.

For functions with local error recovery, your program can call GciSetErrJump to temporarily disable the GciLongJmp mechanism (and to re-enable it afterwards).

Whenever the jump stack is empty, the application must use GciErr to poll for any GemBuilder errors.

The Call Stack

The Smalltalk virtual machine creates and maintains a call stack that provides information about the state of execution of the current Smalltalk expression or sequence of expressions. The call stack includes an ordered list of activation records related to the methods and blocks that are currently being executed. The virtual machine ordinarily clears the call stack before each new expression is executed.

If a soft break or an unexpected error occurs, the virtual machine suspends execution, creates a Process object, and raises an error. The Process object represents both the Smalltalk call stack when execution was suspended and any information that the virtual machine needs to resume execution. If there was no fatal error, your program can call GciContinue to resume execution. Call GciClearStack instead if there was a fatal error, or if you do not want your program to resume the suspended execution.

GemStone System Errors

If your application receives a GemStone system error while linked with GciLnk, relink your application with GciRpc and run it again with an uncorrupted copy of your repository. Your GemStone system administrator can refer to the repository backup and recovery procedures in the System Administration Guide for GemStone/S 64 Bit.

If the error can be reproduced, contact GemStone Customer Support. Otherwise, the error is in your application, and you need to debug your application before using GciLnk again.