The SIMION SL™ Toolkit (version 1.2.1.0 - 2004-11-09)

simion::SLRemote Class Reference

#include <remote.h>

Detailed Description

SL Remote class.

This class forwards remote subroutines calls from SL to subroutines in your C++ program.

Calls are achieved essentially via an interprocess remote procedure call (RPC). For those familiar, this is similar in concept, but simpler than, other remote call mechanisms such as COM.

SYNOPSIS

Example C++ program:

   #include <simion/remote.h>
   //#include <simion/remote.cpp>
   using namepace simion;
  
   void voltage_control(double tof, double& voltage_out)
   {
       if(tof > 1.0) {
           voltage_out = 2;
       } else {
           voltage_out = tof;
       }
   }
   void calculate(double x, double y, double& x_out, double& y_out)
   {
       x_out = x + 5;
       y_out = y + 5;
   }

   int main()
   {
       SLRemote remote;
       remote.handler(1, slremote_handler(voltage_control));
       remote.handler(2, slremote_handler(calculate));
       remote.run();
       remote.wait_for_run_complete();
       return 0;
   }

Corresponding SL program:

   declaresub voltage_control(tof) returns(voltage_out) remote(1)
   declaresub calculate(x,y) returns(x_out, y_out) remote(2)

   sub fast_adjust
       adj_elect01 = voltage_control(ion_time_of_flight)
   endsub

   sub other_actions
       (x, y) = calculate(ion_px_mm, ion_py_mm)
       print("#,#", x, y)
   endsub

CAVEATS

It is very important that the parameter lists of your subroutines in your C++ code match those in your SL code. Otherwise, the C++ code will likely crash.

Be warned that interprocess communication calls are relatively time consuming (e.g. 10-100x in CPU cycles compared to native code), which becomes quite noticeable if you're doing thousands or millions of them (e.g. multiple calls per timestep per ion, such as in the fast_adjust segment). If this is the case, it is desirable to limit the number of real-time remote calls, either by batching multiple calls into a single call or implementing time-critical sections of the code entirely in SL (which compiles to native PRG code and is executed in-process). SL Remote works best when there are a few expensive calls rather than voluminous inexpensive calls into to C++ code.


Public Member Functions
	SLRemote ()
	Constructs a new remoting object.
virtual	~SLRemote ()
	Destructor.
void	handler (int remote_id, slremote_handler handler)
	Registers a callback function and assigns it the given remote ID.
void	run ()
	Starts up a new thread that listens and responds to remote subroutines invoked from the SL code.
void	wait_for_run_complete ()
	Waits for the thread created by the run() call to terminate.
void	debug_trace (bool val)
	Turns debugging on/off.

Member Function Documentation

void simion::SLRemote::debug_trace

(

bool

val

)

Turns debugging on/off.

Parameters:

val

- true if on, else false.

void simion::SLRemote::handler	(	int	remote_id,
		slremote_handler	handler
	)

Registers a callback function and assigns it the given remote ID.

When the SL code invokes the given remote ID, this remoting object will in turn invoke the callback function assigned to that remote ID. The remote ID specified here and the remote ID specified in the SL code must match.

void simion::SLRemote::run

(

)

Starts up a new thread that listens and responds to remote subroutines invoked from the SL code.

This method returns immediately, so you should then call wait_for_run_complete() so that your program doesn't immediately terminate.

void simion::SLRemote::wait_for_run_complete

(

)

Waits for the thread created by the run() call to terminate.

Currently, this waits indefinitely unless debug tracing is enabled.

(If debug tracing is enabled, SLRemote will terminate after a certain number of idle seconds (currently 30) to output the debug log.)

The documentation for this class was generated from the following file:

remote.h

Please report any errors/comments regarding this web page:

SL Libraries -- C++

simion::SLRemote Class Reference

Detailed Description

Public Member Functions

Member Function Documentation