[MAT logo][Prev][Up][Next]

Custom modules - general functions reference

This section describes general functions and so on - functions that don't belong in any of the subsequent sections.

plc_init() is used to initialize a private memory map for a module. This should be called once at the beginning of the module.

plc_done() is used to shut down the library and private memory map for the module. This should be done if the module exits for any reason.

Limitation: The plc_done() function is not particularly complete - it should shut down the module completely, deallocate everything and generally clean the slate enough so that plc_init() could be called again. This is not currently done, mostly through carelessness and because most of the examples are infinite loops, and the rest exit immediately after calling plc_done(). Please file a bug report or ask on the list if you need this fixed.

Return values: plc_init() and plc_done() return returns 0 on success, -1 on failure.

plc_init(module_name, argc, argv);

non real-time
These functions should be called at the beginning and end of each scan. Their effect is to signal the other modules and sleep until it is time for the next scan to begin, as configured by the scan_period and synch options.

Normal usage of these functions is described in the basic custom module chapter. In general terms, plc_scan_beg() should be the first thing in a scan, and plc_scan_end() the last.

Scans should not in general be nested; that is, make sure that these functions are called in alternation. For instance, if you have a long-running loop within your program, you might do the following in the middle:

  plc_update() /* update outputs (may be omitted if nothing was plc_set()) */
  plc_scan_end() /* end scan */
  plc_scan_beg() /* begin new scan */
  plc_update() /* update inputs */

If a module does not have discernible scans, these two functions can be omitted altogether. However, synch, scan_period and similar functionality will not be available for modules that don't call these functions.

Return values: FIXME

int plc_scan_beg(void);
int plc_scan_end(void);
real-time; may sleep on semaphore or timer (as configured)
plc_module_name() Returns the name of the module; memory must be de-allocated with free().

const char *plc_module_name(void);
non real-time
plc_print_usage() Prints a usage summary fragment; call this from your own usage function to print out the command line options handled by plc_init().

Note: this is only applicable if you pass the real argc and argv to plc_init(). If you don't pass argv in, it can't do much about it...

Return values: FIXME

int plc_print_usage(FILE *output);
non real-time
plc_init_try() This function is internal and should not be used by general-purpose modules. FIXME: why is it public?

int plc_init_try(char const *module_name, int argc, char **argv);
non real-time
CLO_xxx definitions Names of command-line options.

#define CLO_LEADER "--PLC"

#define CLO_plc_id             CLO_LEADER "plc_id="
#define CLO_loc_local          CLO_LEADER "local"
#define CLO_loc_isolate        CLO_LEADER "isolate"
#define CLO_loc_shared         CLO_LEADER "shared"
#define CLO_privmap_key        CLO_LEADER "local_map_key="
#define CLO_log_level          CLO_LEADER "debug="
#define CLO_log_file           CLO_LEADER "logfile="
#define CLO_config_file        CLO_LEADER "conf="
#define CLO_module_name        CLO_LEADER "module="
#define CLO_force_init         CLO_LEADER "force-init"


$Date: 2006/05/16 12:46:13 $