Ninf-G client initialization and finalization

Ninf-G uses standard module initializationand finalization. Before any Ninf-G client functions are called, the following function must be called: grpc_initialize (char *config_file_name); This function returns GRPC_OK if Ninf-G was successfully initialized, and you are therefore allowed to subsequently call Ninf-G client functions. Otherwise, GRPC_ERROR is returned, and Ninf-G client functions should not be subsequently called. This function may be called multiple times. To deactivate Ninf-G client, the following function must be called: grpc_finialize (); This function should be called once for each time the Ninf-G client was initialized

Ninf-G Handle Functions

int grpc_function_handle_init (     grpc_function_handle_t *handle,     char *host_name,     int port,     char *func_name ) This function initializes a handle to Ninf-G function along with hostname, port number and function name. A function handle contains information used in referencing a Ninf-G executable offered by the specified host. handle - a handle to Ninf-G function host_name - host name or hostname along with the desired job manager such as ninf.apgrid.org/jobmanager-pbs port - a port number to be used Currently this function ignores this argument and always set to 0. func_name - function name to be used returns GRPC_OK if successfully initialized or GRPC_ERROR if failed int grpc_function_handle_default(     grpc_function_handle_t *handle,     char *func_name) This function initializes Request access to interactive resources at the current time.  A job request is atomic: either all of the requested processes are created, or none are created. handle - the contact information about the resource manager to which the request is submitted. func_name - a RSL description of the requested job int *     grpc_function_handle_destruct (grpc_function_handle_t* handle) This function destruct the handle and returns the result handle - the handle to be destructed. grpc_function_handle_t *     grpc_get_handle (int sessionID) This function returns a handle to the Ninf-G sessionID - the job_contact of the job in question.

Ninf-G Invocation Functions

int grpc_call(grpc_function_handle_t *handle, <argument list>)     This function sends a blocking request to Ninf-G. grpc_call takes as argument the handle to Ninf-G function and the list of arguments in the calling sequence. If the call is successful, it returns GRPC_OK and the result of the computation is stored in the output arguments. If the call fails, it returns GRPC_ERROR. The output arguments are specified in the Ninf IDL. This function is synchronous in that the client waits until the completion of the computation on the server side. int grpc_call_async(grpc_function_handle_t *handle, <agument list>)     This function is almost identical to grpc_call except that it returns immediately after all the arguments have been sent. The return value is the session ID of the asynchronous call. The ID is used for various synchronizations such as waiting for the return value of the call. This function sends a nonblocking request to Ninf-G and returns the job to the caller immediately. This allows the users to invoke multiple sessions simultaneously. grpc_call_async takes as argument the handle to Ninf-G function and the list of arguments in the calling sequence. If the call is successful, it returns the session ID and the result of the computation is stored in the output arguments. If the call fails, it returns GRPC_ERROR. The output arguments are specified in the Ninf IDL.

Ninf-G Invocation Functions using an argument stack and related Functions

grpc_arg_stack * grpc_arg_stack_new( int size ) Allocate an argument stack. The integer argument to grpc_new_arg_stack() represents the max size of the stack. Returns a pointer to the allocated stack object if succeeds and NULL if it fails. int grpc_arg_stack_push_arg( grpc_arg_stack *argStack, void *arg ) Pushes an argument to the stack. Returns GRPC_OK if succeeds and GRPC_ERROR if not. void * grpc_arg_stack_pop_arg( grpc_arg_stack *argstack ) Pops an argument from the stack. Returns pointer to the element if succeeds NULL if some error occured. int grpc_arg_stack_destruct( grpc_arg_stack *argStack ) Free the stack. Returns GRPC_OK if succeeds and GRPC_ERROR if not. int grpc_call_arg_stack( grpc_function_handle_t *handle grpc_arg_stack *argStack ) Performs blocking call. This function corresponds to the grpc_call and the return values are the same. int grpc_call_arg_stack_async( grpc_function_handle_t *handle grpc_arg_stack *argStack ) Performs nonblocking call. This function corresponds to the grpc_call_async and the return values are the same.

	Ninf-G Session Control
	int grpc_probe( int sessionID ) This function probes the job whose session ID is specified in the argument. It returns 1 if the job is done and 0 if not. int grpc_cancel( int sessionID ) This function cancels the job whose session ID is specified in the argument. It returns GRPC_OK if success and GRPC_ERROR if failed.

Ninf-G Wait Functions

int grpc_wait( int sessionID) This function is the most basic call for synchronization, where you wait for the result of the asynchronous call with the supplied session ID. It returns GRPC_OK if the session succeeds and GRPC_ERROR if not. int grpc_wait_and( int * idArray, int length ) This function waits for a set of sessions specified in *idArray to be terminated. It returns GRPC_OK if all the specified sessions succeed and GRPC_ERROR if not. int grpc_wait_or ( int * idArray, int length, int * idPtr ) This function waits for any single session in the sessions specified in *idArray to be terminated. It returns GRPC_OK if the finished session succeeded and GRPC_ERROR if not. The third argument idPtr returns the finished session's ID. If the argument length equals to zero, it returns GRPC_OK and set 0 to the idPtr. int grpc_wait_all() This function waits for all preceding asynchronous invocations made. It returns GRPC_OK if all the sessions succeed and GRPC_ERROR if not. int grpc_wait_any( int *idPtr ) This function waits for any one of the preceding asynchronous invocations made. It returns GRPC_OK if the finished session succeeded and GRPC_ERROR if not. The argument idPtr returns the finished session's ID. If no previous invocation is left, it returns GRPC_OK and set 0 to the idPtr.

Ninf API Reference

	Client activation and deactivation Invocation Functions Session Controls Wait Functions Error Handling Functions

Ninf-G client initialization and finalization

Ninf-G uses standard module initializationand finalization. Before any Ninf-G client functions are called, the following function must be called: Ninf_parse_args (int argc, char *argv[]); Ninf_parse_args analyzes the command line arguments and retrieves arguments for Ninf-G system. Arguments for application itself are kept as command line arguments. This function returns new ARGC if Ninf-G was successfully initialized, and you are therefore allowed to subsequently call Ninf-G client functions. ARGV is also renewed to point to the arguments list for the application. Otherwise, and error code (NINF_ERROR) is returned, and Ninf-G client functions should not be subsequently called.

Ninf-G Invacation Functions

int Ninf_call(char *stub_name, <argument list>)     This function sends a blocking request to Ninf-G. Ninf_call takes as argument the name of Ninf-G function and the list of arguments in the calling sequence. If the call is successful, it returns NINF_OK and the result of the computation is stored in the output arguments. If the call fails, it returns NINF__ERROR. The output arguments are specified in the Ninf IDL. This function is synchronous in that the client waits until the completion of the computation on the server side. int Ninf_call_async(char *stub_name, <agument list>)     This function is almost identical to Ninf_call except that it returns immediately after all the arguments have been sent. The return value is the session ID of the asynchronous call. The ID is used for various synchronizations such as waiting for the return value of the call. This function sends a nonblocking request to Ninf-G and returns the job to the caller immediately. This allows the users to invoke multiple sessions simultaneously. Ninf_call_async takes as argument the handle to Ninf-G function and the list of arguments in the calling sequence. If the call is successful, it returns NINF_OK and the result of the computation is stored in the output arguments. If the call fails, it returns NINF_ERROR. The output arguments are specified in the Ninf IDL.

	Ninf-G Session Control
	int Ninf_session_probe( int sessionID ) This function probes the job whose session ID is specified in the argument. It returns 1 if the job is done and 0 if not. int Ninf_session_cancel( int sessionID ) This function cancels the job whose session ID is specified in the argument. It returns NINF_OK if success and NINF_ERROR if failed.

Ninf-G Wait Functions

int Ninf_wait( int sessionID) This function is the most basic call for synchronization, where you wait for the result of the asynchronous call with the supplied session ID. It returns NINF_OK if the session succeeds and NINF_ERROR if not. int Ninf_wait_and( int * idArray, int length ) This function waits for a set of sessions specified in *idArray to be terminated. It returns NINF_OK if all the specified sessions succeed and NINF_ERROR if not. int Ninf_wait_or ( int * idArray, int length, int * idPtr ) This function waits for any single session in the sessions specified in *idArray to be terminated. It returns NINF_OK if the finished session succeeded and NINF_ERROR if not. The third argument idPtr returns the finished session's ID. If the argument length equals to zero, it returns NINF_OK and set 0 to the idPtr. int Ninf_wait_all() This function waits for all preceding asynchronous invocations made. It returns NINF_OK if all the sessions succeed and NINF_ERROR if not. int Ninf_wait_any( int * idPtr) This function waits for any one of the preceding asynchronous invocations made. It returns NINF_OK if the finished session succeeded and NINF_ERROR if not. The argument idPtr returns the finished session's ID. If no previous invocation is left, it returns NINF_OK and set 0 to the idPtr.

Ninf-G Error Handling Functions

int Ninf_perror ( char *str ) This function writes error messages pointed to by str to standard error. char * Ninf_error_string ( int error_code ) This function returns a pointer to error message which corresponds to the specified error code. int Ninf_get_error ( int sessionID ) This function returns an error code of the session along with the specified sessionID . int Ninf_get_last_error ( ) This function returns the error code of the last session.