Re: [gridrpc-wg] Final call: GridRPC API for inclusion in SAGA 1.0

10 Aug 2006

      Hi Thilo, 

Some comments inlined.

Cheers, Andre.

Quoting [Thilo Kielmann] (Aug 09 2006):
...
Date: Wed, 9 Aug 2006 19:00:49 +0200
From: Thilo Kielmann <kielmann@cs.vu.nl>
To: gridrpc-wg@gridforum.org, saga-rg@gridforum.org
Subject: [gridrpc-wg] Final call: GridRPC API for inclusion in SAGA 1.0
Dear all,
Hidemoto Nakada, Yusuke Tanimura, and myself have met and we have 
re-worked the pending proposal for a GridRPC module for inclusion in
the upcoming SAGA spec. The only thing we have changed is the way in which
parameters to an RPC invocation are passed. Now, it is an array of parameters,
where a paramter is a struct, consisting of buffer, size, and, IN/OUT/INOUT
mode. We have also modelled examples from the Ninf-G web page with this API.
We think that this now has a "look and feel" of GridRPC.
It should have the look & feel of SAGA, and the semantics of
GridRPC :-) - but if it closes in on look & feel on both
ends, so the better of course...
...
Attached please find the proposed text with API and examples.
I felt free to change some part to adapt it to the spec look
and feel (example coding conventions, intendation etc.).
I'll convert that version to tex now, and add it to the
CVS.  Hope thats ok with you.
...
If this (or
something similar) can be agreed upon quickly, then the GridRPC module can
be included in the SAGA 1.0 spec. We see this API not as a competitor to the
GridRPC API, as published in GFD-R.52. It is rather an alternative, embedded
in the SAGA framework, to access existing GridRPC implementations, thus
extending their user base.
We are now doing the final call for comments for the two groups involved.
If you have comments or questions, please post them TO BOTH MAILING LISTS.
This final call is open until FRIDAY, AUGUST 18th.
There is one conflict: I hope that we can get the SAGA CORE
spec into final mailing list call on Monday.  So I suggest
to NOT move that timeline backwards, but to include rpc
already - if either of the final calls meets negative
comments we remove it - does that make sense?

More comments below
...
Comments and objections made by then will happily be included in the
proposal. By this deadline, we will add this text (with all modifications
we got) into the SAGA API document.
Thanks to you all for your contributions.
Thilo Kielmann
...
+-------------------------------------------------------------+
######  ######   #####
                  #     # #     # #     #
                  #     # #     # #
                  ######  ######  #
                  #   #   #       #
                  #    #  #       #     #
                  #     # #        #####
+-------------------------------------------------------------+
Summary:
========
GridRPC is one of the few high level APIs defined by the GGF.
  Including it into the SAGA API benefits both:  SAGA gets more
  complete, and provides a better coverage of its use cases with
  a single look and feel; and GridRPC gets embedded into a set
  of other tools of similar scope, which opens it to
  a potentially wider user community, and ensures its further
  development.
The RPC package of the SAGA API described here is a one to one
  mapping from the GridRPC standard, equipped with the SAGA look
  and feel, error conventions, task model etc.
+-------------------------------------------------------------+
Specification:
==============
package saga version 0.1 
  {
    package rpc 
    {
      enum io_mode 
      {
        In    = 1,  // input  parameter
        Out   = 2,  // output parameter
        InOut = 3   // both input and output parameter
      }
struct parameter
      {
        long        size;     // number of bytes in buffer
        array<byte> buffer;   // data
        io_mode     mode;     // parameter mode
      }
class rpc 
      {
        CONSTRUCTOR (in    string            funcname  );
        call        (inout array<parameter>  parameters);
      }
    }
  }
+-------------------------------------------------------------+
#ifndef SHORT
Details:
========
class rpc:
  ----------
This class represents a remote function handle, which 
    can be called (repeatedly), and returns the result of 
    the respective remote procedure invocation.
The class offers one non trivial constructor, which
    initialises the remote function handle (see [1] for
    details).  That process may involve connection setup,
    service discovery etc.  The class further offers one method
    'call()', which invokes the remote procedure, and returns 
    the respective return data and values.
In the constructor, the remote procedure to be invoked 
    is specified by a URL, whith the syntax:
gridrpc://server.net:1234/my_function
with the elements responding to:
gridrpc     - scheme - identifying a grid rpc operation
      server.net  - server - server host serving the rpc call
      1234        - port   - contact point for the server
      my_function - name   - name of the remote method to invoke
All elements but the scheme can be empty, which allows the
    implementation to fall back to some default remote method to
    invoke (minimal URL: gridrpc:///).
The description of the constructor says that the URL can be
NULL, in some languages that will mean 'empty' (e.g. if they
have no default args).  That would mean that scheme can be
empty, too.
...
The argument and return value handling is currently very
    basic, and reflects the traditional scheme for remote
    procedure calls: an array of parameters, for each of which
    the buffer, its size, and the input/output mode is
    described.  On invocation of the 'call' method, for each
    parameter the 'mode' value has to be initialized, for
    parameters with mode 'In' or 'InOut', also 'size' and 'buffer'
    must be initialized.  For parameters with mode OUT, 'size'
    might also have the value 0 in which case the 'buffer' is
    considered to be void, and has to be created (e.g.,
    allocated) by the SAGA system upon arrival of the result
    data.
Not that I disagree, but it should be noted that even for
RPC calls which require input parameters only, the params
must be passed by reference.  That implies, in some
languages, to track the param memory for async invokations,
where that is not the case for async invokations of other
languages which don't have no output parameters.  It can;t
be helped I guess, and should not be an issue really.
...
This argument handling scheme allows efficient (zero-copy)
    passing of parameters. For 'Out' parameters with a size value
    of 0, the implementation is required to allocate the data
    structure and to overwrite the size and buffer fields for
    the parameter.
It is the responsibility of the application programmer to
free this memory I assume?  The the language bindings MUST
prescribe how that memory is allocated, to allow the
application to choose the appropriate de-allocation method.
Alternatively we would need an 'dealloc' method, which would
then require the implementation to alloc and de-alloc the
params (and to keep track of the blocks).
...
- constructor
      Purpose: inits a remote function handle
      Format:  CONSTRUCTOR  (in  session session, 
                             in  string  funcname)
      Inputs:  session:      saga session to use
               funcname:     name of remote method to
                             initialize
      Outputs: -
      Throws:  NoSuccess:          server could not be
                                   contacted, or method is 
                                   unknown
I assume a number of other exceptions would apply as well,
such as 

  AuthenticationFailed
  AuthorizationFailed
  PermissionDenied
  DoesNotExist (server contacted, but no such call available)
  IncorrectURL

Well, and some more I guess.  Question is: NoSuccess is
actually reserved as last resort, if no other exception
really applies (its the least specific exception, please
have a look at the 'error handling' section in the spec).
So, is NoSuccess really needed here, and in what conditions?
...
Notes:   - see [1] for details
               - if funcname is NULL, a default handle is 
                 created
- call
      Purpose: call the remote procedure
      Format:  call         (inout array<parameter> param);
      Inputs:  - 
      In/Out:  param:        argument/result values for call
      Outputs: - 
      Throws:  NoSuccess:    remote operation failed
Same as above.
...
Notes:   - see [1] for details
               - by passing an array of variable size, 
                 different numbers of parameters can be 
                 handled. No special variable argument
                 list handling is required.
We discussed varargs at one of the last GGF, and came to the
conclusion that language bindings COULD allow varargs.  That
does not make sense with the proposed scheme, in particular
in respect to the memory allocation policy described.  So, I
guess we abstain from varargs in the language bindings then?

Other open questions we had from former RPC discussions,
and which should be addressed in this spec, are:

  - GridRPC takes a config file name on initialization.
    That config file needs to be user specific IIUC, and
    there was some discussion, but no conclusion about that.
    So, what is the appraoch on that?  Is that spec
    implementable on top of GridRPC, and how?  If that is an
    issue still: our decision was to include the config file
    URL as (optional) parameter to the CONSTRUCTOR.  Does
    that make sense?

  - The RPC spec is silent about 'when' the connection to
    the remote server is made, on creation of the handle, or
    on call().  We decided in other parts of the spec that,
    for example, the constructor opens a file, or remote
    connection.  I propose to prescribe the same for RPC.
    Does that make sense?  Do we need to loosen the
    semantics elsewhere in the spec? (IMHO not).

  - Ninf-G allows to bind a handle to multiple calls.  I
    assume that this is hidden in the implementation for
    now, and has no explicit reflection in the API?  I think
    that is what we decided on anyway...

  - should we add a 'cancel(in float timeout)'?  Explicit
    resource dealloction was an issue in our discussion at
    GGF, and we agreed on cancel - is that not needed
    anymore?

Cheers, Andre.
...
+-------------------------------------------------------------+
Examples:
=========
  // c++ example
  // call a remote matrix multiplication A = A * B
  try 
  {
    rpc rpc ("gridrpc://fs0.das2.cs.vu.nl/matmul1");
std::vector <saga::rpc::parameter> params (2);
params[0].buffer = // ptr to matrix A
    params[0].size   = sizeof (buffer);
    params[0].mode   = saga::rpc::InOut;
params[1].buffer = // ptr to matrix B
    params[1].size   = sizeof (buffer);
    params[1].mode   = saga::rpc::In;
rpc.call (params);
// A now contains the result
  }
  catch ( const saga::exception & e)
  {
    std::err << "SAGA error: " << e.what () << std::endl;
  }
// c++ example
  // call a remote matrix multiplication C = A * B
  try 
  {
    rpc rpc ("gridrpc://fs0.das2.cs.vu.nl/matmul2");
std::vector <saga::rpc::parameter> params (3);
params[0].buffer = NULL;  // buffer will be created
    params[0].size   = 0;     // buffer will be created
    params[0].mode   = saga::rpc::Out;
params[1].buffer = // ptr to matrix A
    params[1].size   = sizeof (buffer);
    params[1].mode   = saga::rpc::InOut;
params[2].buffer = // ptr to matrix B
    params[2].size   = sizeof (buffer);
    params[2].mode   = saga::rpc::In;
rpc.call (params);
// params[0].buffer now contains the result
  }
  catch ( const saga::exception & e)
  {
    std::err << "SAGA error: " << e.what () << std::endl;
  }
// c++ example
  // asynchronous version of A = A * B
  try 
  {
    rpc rpc ("gridrpc://fs0.das2.cs.vu.nl/matmul1");
std::vector <saga::rpc::parameter> params (2);
params[0].buffer = // ptr to matrix A
    params[0].size   = sizeof (buffer);
    params[0].mode   = saga::rpc::InOut;
params[1].buffer = // ptr to matrix B
    params[1].size   = sizeof (buffer);
    params[1].mode   = saga::rpc::In;
saga::task t = rpc.call <saga::task::ASync> (params);
t.wait ();
    // A now contains the result
  }
  catch ( const saga::exception & e)
  {
    std::err << "SAGA error: " << e.what() << std::endl;
  }
// c++ example
  // parameter sweep example from
  // http://ninf.apgrid.org/documents/ng4-manual/examples.html
  //
  // Monte Carlo computation of PI
  //
  try 
  {
    std::string   uri[NUM_HOSTS]; // initialize...
    long times, count[NUM_HOSTS], sum;
std::vector <saga::rpc::rpc> servers;
// create the rpc handles for all URIs
    for ( int i = 0; i < NUM_HOSTS; ++i )
    {
      servers.push_back (saga::rpc::rpc (uri[i]));
    }
// create persisten storage for tasks and parameter structs
    saga::task_container tc;
    std::vector <std::vector <saga:rpc::parameter> > params;
// fill parameter structs and start async rpc calls
    for ( int i = 0; i < NUM_HOSTS; ++i )
    {
      std::vector <saga::rpc::parameter> param (3);
param[0].buffer = i; // use as random seed
      param[0].size   = sizeof (buffer);
      param[0].mode   = saga::rpc::In;
param[1].buffer = times;
      param[1].size   = sizeof (buffer);
      param[1].mode   = saga::rpc::In;
param[2].buffer = count[i];
      param[2].size   = sizeof (buffer);
      param[2].mode   = saga::rpc::Out;
// start the async calls
      saga::task t = servers[i].call <saga::task::ASync> (param);
// save the task;
      tc.add (t[i]);
// save the parameter structs
      params.push_back (param);
    }
// wait for all async calls to finish
    tc.wait (-1, saga::task::All);
// compute and print pi
    for ( int i = 0; i < NUM_HOSTS; ++i )
    {
      sum += count[i];
    }
std::out << "PI = " 
             << 4.0 * ( sum / ((double) times * NUM_HOSTS))
             << std::endl;
  }
  catch ( const saga::exception & e)
  {
    std::err << "SAGA error: " << e.what () << std::endl;
  }
+-------------------------------------------------------------+
Notes:
======
References:
  -----------
[1] H. Nakada, S. Matsuoka, K. Seymour, J.Dongarra, 
        C. Lee, H.  Casanova: "A GridRPC Model and API for End-User
        Applications", Global Grid Forum Document GFD-R.52.
Comparision to the original GridRPC calls:
  ------------------------------------------
initialization:
    ---------------
- grpc_initialize
GridRPC: reads the configuration file and initializes the
               required modules.
      SAGA:    not needed, implicit
- grpc_finalize
GridRPC: releases any resources being used
      SAGA:    not needed, implicit
handle management:
    ------------------
- grpc_function_handle_default
GridRPC: creates a new function handle using the default
               server.  This could be a pre-determined server 
               name or it could be a server that is dynamically 
               chosen by the resource discovery mechanisms of 
               the underlying GridRPC implementation, such as 
               the NetSolve agent.
      SAGA:    default constructor
- grpc_function_handle_init
GridRPC: creates a new function handle with a server
               explicitly specified by the user.
      SAGA:    explicit constructor
- grpc_function_handle_destruct
GridRPC: releases the memory associated with the
               specified function handle.
      SAGA:    destructor
- grpc_get_handle
GridRPC: returns the handle corresponding to the given
               session ID (that is, corresponding to that 
               particular non-blocking request).
      SAGA:    not possible right now.
               However, status of asynchronous operations can be checked
               via the corresponding task objects.
call functions:
    ---------------
- grpc_call
GridRPC: makes a blocking remote procedure call with a variable
               number of arguments.
      SAGA:    has no variable number of aguments, this case is covered
               via the SAGA version of grpc_call_argstack.
- grpc_call_async
GridRPC: makes a non-blocking remote procedure call with a
               variable number of arguments.
      SAGA:    done via task model and equivalent to grpc_call_argstack.
- grpc_call_argstack
GridRPC: makes a blocking call using the argument stack
      SAGA:    call provides a parameter array of variable size
- grpc_call_argstack_async
GridRPC: makes a non-blocking call using the argument stack.
      SAGA:    done via the task model and call
asynchronous control functions:
    -------------------------------
- grpc_probe
GridRPC: checks whether the asynchronous GridRPC call has
               completed.
      SAGA:    done via the task model
- grpc_cancel
GridRPC: cancels the specified asynchronous GridRPC call.
      SAGA:    done via the task model
asynchronous wait functions:
    ----------------------------
- grpc_wait
GridRPC: blocks until the specified non-blocking requests to
               complete.
      SAGA:    done via the task model
- grpc_wait_and
GridRPC: blocks until all of the specified non- blocking requests
               in a given set have completed.
      SAGA:    done via the task container
- grpc_wait_or
GridRPC: blocks until any of the specified non- blocking requests
               in a given set has completed.
      SAGA:    done via the task container
- grpc_wait_all
GridRPC: blocks until all previously issued non-blocking requests
               have completed.
      SAGA:    done via the task container
- grpc_wait_any
GridRPC: blocks until any previously issued non-blocking request
               has completed.
      SAGA:    done via the task container
error reporting functions:
    --------------------------
- grpc_perror
GridRPC: prints the error string associated with the last GridRPC
               call.
      SAGA:    exceptions
- grpc_error_string
GridRPC: returns the error description string, given a numeric
               error code.
      SAGA:    exceptions
- grpc_get_error
GridRPC: returns the error code associated with a given
               non-blocking request.
      SAGA:    exceptions
- grpc_get_last_error
GridRPC: returns the error code for the last invoked GridRPC call.
      SAGA:    exceptions
+-------------------------------------------------------------+
#endif // SHORT
-- 
"So much time, so little to do..."  -- Garfield

Re: [gridrpc-wg] Final call: GridRPC API for inclusion in SAGA 1.0

Andre Merzky