servers.run - Function

Run a function in an object

Synopsis
run(id, invokerecord, async)

Description
The run function runs a member function in the specified C++ object.

The server that will be used is specified by the id parameter. The object, function within that object, and parameters within that function are specified using the invokerecord argument.

There are two special fields in the invokerecord argument. These are ``_method'' and ``_sequence''. The first of these indicates which function to run and hence should be a string that matches one returned by the methods member function in the C++ object. I do not know what the ``_sequence'' argument does but I guess that it indicates which C++ object to use. The value to use for the second argument is the _sequence field in the record returned by the create function as shown in the example below.

Other fields in the invokerecord function are only required if the specified function needs user supplied parameters. The field names must match the name given to the ``Parameter'' object associated with the specified function.

The async argument controls whether or not to wait for the execution of C++ function to complete. Functions that are quick to compute are normally run synchronously. When a function is run synchrounously the return value of this function is the return value of the C++ function, or T if the C++ function returns a void.

When the function is run asynchronously the return value is a small integer that identifies the job. This job id can be used in conjunction with the running function to determine when the function has finished. When a function has finished the job id can be used in conjunction with the result function to get the return value of the function.

This function can also return a fail if something bad has happened.

Arguments

id	Identifies which server to use
	Allowed:	A positive integer obtained from the activate function.
	Default:	no default
invokerecord	Parameters for the function that will be run
	Allowed:	A record with the required fields
	Default:	no default
async	Return before the function has completed?
	Allowed:	T or F
	Default:	F

Returns
T, an integer or a fail

Example

      private.getlabelRec := [_method = 'getlabel',
			      _sequence = private.toolid._sequence];
      public.getlabel := function(which) {
        wider private;
        private.getlabelRec.which := which;
        return defaultservers.run(private.serverid, private.getlabelRec);
      }

This example shows how to use the run function to call a C++ function that has one parameter, the which argument. This function is always run synchronously and hence the return value of the run function is the return value of the C++ function ie., the label string.

Next: servers.done - Function Up: servers - Tool Previous: servers.add - Function Contents Index

	Package	utility
	Module	tasking
	Tool	servers