The GRAPE Function

 

The GRAPE kernel consists of a set of functions which handle the message passing, i.e. invoke the appropriate function for the desired method on an instance or class.The main function will be invoked by

GRAPE(obj, message)

where obj is a pointer to the object which should receive the message given by a simple string. This string defines the name of the method. This GRAPE command supplies a pointer to the appropriate function which implements the method. The method will be executed if a parameter list (which might be empty) is supplied. Therefore a typical grape command looks like this

GRAPE(obj, message)(parm1, parm2, ...)

With an empty parameter list -- don't forget the empty parenthesis -- it should look like this

GRAPE(obj, message)()

The structure of the message string defines the precedence to search for the corresponding function. No option given starts searching in the class of obj. If the message has a leading "=", the method is searched in the actual method's class. A leading "^" commences search in the superclass of the actual method class, multiple "^"'s can be used to skip superclasses. Additionally it is possible to use G_CAST_CLASS(obj, class) as object, then the search starts in class class. This should be preferred to using multiple "^"'s because it is easier to read and independent from changes in the class hierarchy.

implementing a new method all sub- and superclasses should be searched for methods with the same name. The new method should have the same parameter structure as these already existing equally named methods, this helps avoiding problems with inheritance.

There are two kinds of methods that can be used interactively. So called ``display methods'' are used to update the graphic window (see section 4.3.2), they should be marked by the suffix "-disp". The standard display method is called "display", it works on nearly every existing geometric object and should be implemented for every new geometry class (see section 5.4.6). Methods that can be send interactively to an object (e.g. a numerics method that can be started by a button press) should have the suffix "-send". Both types of methods obviously must be parameterless, parameters for them can for example be provided by rulers (see sections 5.4.6 and 5.5.5).

Now, what happens when you call GRAPE(obj, message)? Let message be the non-prefixed method "name", obj an instance of class Dummy. Then

• GRAPE searches the methods defined on the class Dummy of obj for the method "name".
• If there is no method "name" on Dummy, perhaps there is one on the superclass of Dummy? Or on the superclass of the superclass? And so on.
• If no method "name" was found GRAPE looks for a method "universal" (see section 5.4.8), again first the class and then the superclasses will be searched.
• Having terminated the search, GRAPE pushes obj on an internal stack together with information on the method, primarily the method's class, i.e. the ancestral class the method is inherited from.
• Finally, GRAPE returns the address of the function related to the method. If neither "name" nor "universal" were found an error message is printed and a pointer to an error handler (an empty method) is returned instead.

The function returned by GRAPE when called obtains the obj by START_METHOD which just looks up the internal stack. The complementary END_METHOD pops the last item (obj + method information) from the stack. The use of START_METHOD and END_METHOD is illustrated in section 5.4. As mentioned before the class the search starts in can be influenced by using the prefixes "=" and "^" or G_CAST_CLASS.

There some points about the GRAPE call you should be aware of:

• Since the function which is determined by GRAPE is not known at compile-time, the compiler cannot do any type-checking for the argument list. Yet, the compiler performs the usual type promotions (float double, short int int, char int), so keep to self-promoting types in the parameter list of your ANSI C method routine (alternatively it could be declared in the obsolete K&R style, then the same type conversions are done, but this in not recommended).
• A common error is to forget an empty argument list () to the GRAPE call. In this case the object returned by the method is the function pointer, continuing to work with this ``object'' has crashed one of our SGI machines before
• It is not allowed to store the function pointer returned by GRAPE(obj, message) and to call the corresponding method function more than once. From the second call on START_METHOD returns a wrong object to the method, the program might crash if this object has the wrong class.
• Don't send prefixed method names to objects of another class than the object obtained by START_METHOD and only use G_CAST_CLASS to cast the object to one of its superclasses.