6.3.2 Initialization functions

The following functions are intended to be called fairly early in the generated code.

Function: void ncptl_init (int version, char *program_name)

Initialize the coNCePTuaL run-time library. version is used to verify that runtimelib.c corresponds to the version of ncptl.h used by the generated code. The caller must pass in NCPTL_RUN_TIME_VERSION for version. program_name is the name of the executable program and is used for outputting error messages. The caller should pass in argv[0] for program_name. ncptl_init() must be the first library function called by the generated code (with a few exceptions, as indicated below).

Function: void ncptl_permit_signal (int signalnum)

Indicate that the backend relies on signal signalnum for correct operation. Because signal handling has performance implications, the coNCePTuaL run-time library normally terminates the program upon receiving a signal. Hence, the user can be assured that if a program runs to completion then no signals have affected its performance. See Running coNCePTuaL programs, for a description of the --no-trap command-line option, which enables a user to permit additional signals to be delivered to the program (e.g., when linking with a particular implementation of a communication library that relies on signals). ncptl_permit_signal() must be invoked before ncptl_parse_command_line() to have any effect.

Function: void ncptl_parse_command_line (int argc, char *argv[], NCPTL_CMDLINE *arglist, int numargs)

Parse the command line. argc and argv should be the argument count and argument vector passed to the generated code by the operating system. arglist is a list of descriptions of acceptable command-line arguments and numargs is the length of that list.

Because ncptl_init() takes many seconds to run, it is common for generated code to scan the command line for --help or -? and, if found, skip ncptl_init() and immediately invoke ncptl_parse_command_line(). Doing so gives the user immediate feedback when requesting program usage information. Skipping ncptl_init() is safe in this context because ncptl_parse_command_line() terminates the program after displaying usage information; it does not require any information discovered by ncptl_init() .

Most generated programs have a --seed/ -S option that enables the user to specify explicitly a seed for the random-number generator with --help/ -? showing the default seed. ncptl_seed_random_task() must therefore be called before ncptl_parse_command_line() which, as stated in the previous paragraph, can be invoked without a prior invocation of ncptl_init(). Consequently, it can be considered safe also to invoke ncptl_seed_random_task() before ncptl_init().

A generated program’s initialization routine will generally exhibit a structure based on the following pseudocode:

if “--help” or “-?” in command-line options then
   only_help := TRUE
else
   only_help := FALSE
   ncptl_init(…)
end if
random_seed := ncptl_seed_random_task(0)
ncptl_parse_command_line(…)
if only_help = TRUE then
   ncptl_error("Internal error; should have exited")
end if
ncptl_seed_random_task(random_seed)