3 Creating and setting up server-side programs

• 3.1 Creating a Ninf-G Executable
• 3.2 Setting up the Ninf-G Executable operating environment
• 3.3 Specifications for the configuration file used by Ninf-G Executable
  • 3.3.1 Structure of the configuration file
  • 3.3.2 Attributes and attribute values

3.1 Creating a Ninf-G Executable

• Describing the interface information with Ninf-G IDL

  The following kinds of information are described with IDL.

  • Module name (Ninf-G Executable identifier)
  • Interface information
  • Other information required by Ninf-G Executable

  The following is a sample of IDL for implementing matrix multiplication. For detailed Ninf-G IDL specifications, see chapter 6, "Ninf-G IDL Specifications".

  Ninf-G IDL sample

  Module mmul; Define dmmul(IN int n, IN double A[n][n], IN double B[n][n], OUT double C[n][n]) "... description ..." Required "libxxx.o" /* specify library including this routine. */ Calls "C" mmul(n,A,B,C); /* Use C calling convention. */

  The following is an example of a "callback", that can be described with Ninf-G IDL.

  Ninf-G IDL sample (callback)

  Module test; Define callback_test(IN int a, OUT int *b, callback_func(IN int c[1], OUT int d[1])) { int executableStatus, clientStatus; executableStatus = calc(a, b); callback_func(executableStatus, &clientStatus); if (d == 1) { /* client is alive */ } }

• Implementation of remote functions and remote methods

  The required remote functions and remote methods (those called in the IDL) must be implemented (in C or FORTRAN).

  The source code (C) for the mmul() function used in the Ninf-G IDL sample shown above is presented below.

  Remote function (Remote method) sample

  void mmul(int n, double * a, double * b, double * c) { double t; int i, j, k; for (i = 0; i < n; i++) { for (j = 0; j < n; j++) { t = 0; for (k = 0; k < n; k++){ t += a[i * n + k] * b[k * n + j]; } c[i * n + j] = t; } } }

  Note: Implementing cancel processing

  When implementing processing for canceling a session, call grpc_is_canceled_np() in the Ninf-G Executable Library API from within a remote function or remote method and check the return value. Coding for performing session cancel processing if the return value is 1 is needed.

  Example of cancel processing implementation

  #include <grpc_executable.h> void mmul(int n, double * a, double * b, double * c) { grpc_error_t err; double t; int i, j, k; for (i = 0; i < n; i++) { for (j = 0; j < n; j++) { t = 0; for (k = 0; k < n; k++){ t += a[i * n + k] * b[k * n + j]; } c[i * n + j] = t; } if (grpc_is_canceled_np(&err) == 1) { /* canceled */ break; } } }

  
  
• Using the Ninf-G generator to compile the IDL

  % ${NG_DIR}/bin/ng_gen

  Executing the above command generates the following.

  • Ninf-G stub for executing a remote function (remote method)
  • makefile for generating a Ninf-G Executable
  
  
• Creating the Ninf-G Executable

  The makefile generated by the stub generator is used to execute the make command.

  % make -f <module_name>.mak

  An executable Ninf-G Executable and NRF file is generated.

  If you use Information Service MDS4 for information retrieval, copy the generated NRF file (*.nrf) to $GLOBUS_LOCATION/var/gridrpc on the gatekeeper node, which was set for Information Service MDS4 server.

3.2 Setting up the Ninf-G Executable operating environment

• Preparing the configuration file for use by Ninf-G Executable

  Prepared according to the need for a configuration file for adjusting the location of the temporary files generated during filename type argument processing and for the log output.

  • User settings

    Write ".ngstubrc" in the user's home directory.

3.3 Specifications for the configuration file used by Ninf-G Executable

3.3.1 Structure of the configuration file

The Ninf-G Executable configuration file is a text file which contains the settings information that is required for operation of Ninf-G Executable.

• This file is placed on the server on which Ninf-G Executable runs.
• The user definition file (user settings file) is placed in the user's home directory. The file name is .ngstubrc.

An example of entries in the Ninf-G Executable configuration file is shown below.

#comment

attribute    value    # comment

attribute    value    # comment
attribute    value    # comment

...

• Each line consists of an attribute and its value.
• One line defines one attribute.
• What follows after a pound sign (#) is interpreted as a comment.
• The attribute and attribute value must be separated by one or more spaces or by a TAB character.
• Multiple attributes cannot be written on one line.
• The attribute and attribute value must be written on the same line.
• One attribute definition cannot extend over more than one line.
• An attribute must have a defining attribute value. An attribute alone defines nothing.
• Attribute values of attributes for which multiple definitions are possible cannot overlap.

The following description produces an error.

AttributeValue
        #  No delimiter between attribute and attribute value

Attribute    Value    Attribute    Value
        # Multiple attributes on a line

Attribute
Value
        #  attribute value extend across more than one line

Attribute
        #  No attribute value

tmp_dir /tmp
tmp_dir /var/tmp
        # Overlapping of the attribute values of an attribute
        #  that can not have multiple definitions

3.3.2 Attributes and attribute values

The attributes and their attribute value definitions are listed below.

tmp_dir                        Directory
loglevel                       [0-5]
loglevel_ninfgProtocol         [0-5]
loglevel_ninfgInternal         [0-5]
log_filePath                   File name
log_suffix                     Suffix
log_nFiles                     Number of files
log_maxFileSize                Number of bytes
log_overwriteDirectory         [true/false]
commLog_enable                 [true/false]
commLog_filePath               PathFile name
commLog_suffix                 Suffix
commLog_nFiles                 FilesNumber of files
commLog_maxFileSize            FileSizeNumber of bytes
commLog_overwriteDirectory     [true/false]
save_stdout                    File name
save_stderr                    File name
handling_signals               Signals ...
continue_on_error              [true/false]
communication_proxy_log_filePath path of logfile

The definable attributes and attribute values are listed below.

The meanings of the log level values are described below.

• tmp_dir (temporary file directory)

  The directory in which temporal files are placed for passing the filename type arguments to a remote method.

  When omitted, if TMPDIR environment variable is defined, it is used; otherwise, "/tmp" is used.

• loglevel* (log level)

  The log level is specified for all log categories by loglevel and for each category individually by loglevel_*.

  When the log level for each category has not been specified, the log level for all categories is applied.

  When omitted, the value of the NG_LOG_LEVEL environment variable is used.
  If the NG_LOG_LEVEL environment variable is not set, 2 (Error) is used as the default value of loglevel.

• log_filePath (log file name)

  The name of the file to which the log is output is specified in the log file name.

  The file name may include a path that includes a directory (e.g., "/home/myHome/var/logFile").

  The file and directory name can include the following specifiers.

  • "%t"

    "%t" is replaced with the date as year, month and day, and the time in hours, minutes, seconds and milliseconds ("yyyymmdd-hhmmss-MMM") (e.g., "/ home/myHome/var/logDir%t/logFile" is replaced by "/home/myHome/var/logDir20030101-154801-123/logFile").

  • "%h"

    "%h" is replaced with the Ninf-G Executable hostname.

  • "%p"

    "%p" is replaced with the process id of the Ninf-G Executable.

  The Ninf-G Executable id number is added to the end of the file name.

  When omitted, the log is output to standard error. If the log file name is omitted, the log_suffix, log_nFiles, and log_maxFileSize are ignored.

  Note: When the Ninf-G Executable exits abnormally on startup, the executable id is not added and the hostname and process id are added to the end of the file name.

• log_suffix (log file suffix)

  When a log file is specified, this specifies the suffix used when the log file is created.

  If a suffix is specified, the generated file name will be from "filename[000].suffix" to "filename[nnn].suffix". If omitted, the generated file name will be from "filename.[000]" to "filename.[nnn]". The number of files minus 1 is "nnn."

  The number of digits in "nnn" is the same as the number of digits in number of files minus 1. For example, if the number of files is set to 100, then the number will range from "00" to "99."

• log_nFiles (the number of files for log output)

  This is the number of files created for log output.

  0 indicates that an unlimited number of files can be output. A negative value results in an error.

  If omitted, the value 1 is used.

• log_maxFileSize (maximum number of bytes for the log file)

  This is the maximum number of bytes for the log file. A unit indicator from among "kKmMgG" can be appended to the numerical value to indicate Kilobytes (1024 bytes), Megabytes (1024 Kbytes), or Gigabytes (1024 Mbytes).

  If omitted, the value will be unlimited if the number of files is one, or 1 Mbyte if the number of files is two or more.

• log_overwriteDirectory (over-write permission for the directory in which the log files are generated)

  This establishes overwrite permission for the directory. If the specified directory exists, this specifies whether the creation of log files in that directory is enabled or disabled.

  Operation in the case that the directory exists is shown below.

  • true: If the file specified by log_filePath exists in the directory, that file is overwritten.
  • false: Error.

• commLog_enable (whether communication log output is enabled or disabled)

  This specifies whether the communication log output function is enabled or disabled. If 'true' is specified, the communication log is output. If not specified, the default value is false.

• commLog_filePath (communication log file name)

  The name of the file to which the communication log is output is specified in the log file name.

  The file name may include a path that includes a directory (e.g., "/home/myHome/var/logFile").

  The file and directory name can include the following specifiers.

  • "%t"

    "%t" is replaced with the date as year, month and day, and the time in hours, minutes, seconds and milliseconds ("yyyymmdd-hhmmss-MMM") (e.g., "/ home/myHome/var/logDir%t/logFile" is replaced by "/home/myHome/var/logDir20030101-154801-123/logFile").

  • "%h"

    "%h" is replaced with the Ninf-G Executable hostname.

  • "%p"

    "%p" is replaced with the process id of the Ninf-G Executable.

  The Ninf-G Executable id number is added to the end of the file name.

  When omitted, the log is output to standard error. If the communication log file name is omitted, the commLog_suffix, commLog_nFiles, and commLog_maxFileSize are ignored.

• commLog_suffix (communication log file suffix)

  When the communication log file is specified, this specifies the suffix used when the log file is created.

  If a suffix is specified, the generated file name will be from "filename[000].suffix" to "filename[nnn].suffix". If omitted, the generated file name will be from "filename.[000]" to "filename.[nnn]". The number of files minus 1 is "nnn."

  The number of digits in "nnn" is the same as the number of digits in the number of files minus 1. For example, if the number of files is set to 100, then the number will range from "00" to "99."

• commLog_nFiles (number of files for communication log output)

  This is the number of files created for communication log output.

  0 indicates an unlimited number of files can be output. A negative value results in an error.

  If omitted, the value 1 is used.

• commLog_maxFileSize (maximum number of bytes for the communication log file)

  This specifies the maximum number of bytes for the communication log file. A unit indicator from among "kKmMgG" can be appended to the numerical value to indicate Kilobytes (1024 bytes), Megabytes (1024 Kbytes), or Gigabytes (1024 Mbytes).

  If omitted, the value is either unlimited if the number of files is one or 1 Mbyte if the number of files is two or more.

• commLog_overwriteDirectory (over-write permission for the directory in which the communication log files are generated)

  This establishes overwrite permission for the directory. If the specified directory exists, this specifies whether the creation of log files in that directory is enabled or disabled. Operation in the case that the directory exists is shown below.

  • true: If the file specified by log_filePath exists in the directory, that file is overwritten.
  • false: Error.

• save_stdout (Save stdout to file)

  This specifies the file name to save stdout.

  If this attribute is set, stdout is saved to the specified file.

  If the given file name for both save_stdout and save_stderr attribute is the same, output is shared to one file in arbitrary order.

  The output file is opend by append mode.

  If omitted, stdout output is delivered to Ninf-G Client or discarded.

• save_stderr (Save stderr to file)

  This specifies the file name to save stderr.

  If this attribute is set, stderr is saved to the specified file.

  If the given file name for both save_stdout and save_stderr attribute is the same, output is shared to one file in arbitrary order.

  The output file is opend by append mode.

  If omitted, stderr output is delivered to Ninf-G Client or discarded.

• handling_signals

  This attribute specifies signals which will be caught by Ninf-G Executable.

  When the Ninf-G Executable catches the signal, Ninf-G cleans up all temporary files, and exits. This clean up process is performed only for signals which are specified in this attribute.

  The signals are specified by either signal name or signal number. Multiple signals can be specified by space-delimited enumeration. The value "none" can be specified if no signals need to be caught.

  If omitted, SIGINT, SIGTERM and SIGHUP will be caught by Ninf-G Executable.

• continue_on_error (continue computation if an error occurs)

  This attribute is used to control behaviors of a Ninf-G Executable when a communication error occurs. Such a communication includes explicit one (e.g. data transfer) as well as implicit one (e.g. heartbeating).

  If the value is set to 'false', which is the default value, the Ninf-G Executable immediately exits from its execution when a communication error occurs. This enables Ninf-G Executables to release computing resources immediately after the error. It is also useful to avoid Ninf-G Executables remaining as zombie processes when the Ninf-G Client would die.

  If the value is set to 'true', a Ninf-G Executable does not exit and continues to run until the callee function or method will be completed. This configuration is valuable if the callee functions and methods record results of the computation as files in the server machines. In this case, it may be worth to continue the execution of the Ninf-G Executable even if a communication error occurs.

  If omitted, the value 'false' is used.

  Note: Even if the value is set to true, Ninf-G Executables may exit by catching signals from queueing system like SGE or PBS, when the Ninf-G Client was killed by SIGHUP, SIGINT or SIGTERM signal.

  Note: In order for Ninf-G Executables to detect an error immediately when the connection to the Ninf-G Client was closed, Ninf-G Executables must be configured as Pthread version.

• communication_proxy_log_filePath (log file path)

  This specifies the log file name for Remote Communication Proxy.

  If omitted, log file is not generated