GASS: Server Function Reference

Overview
GASS Server Activation and Deactivation
Functions

GASS Server Overview

The GASS server API is used to construct a server that can service get and put requests made by the GASS client API using x-gass URLs. Each of these operations can be performed to/from memory, to/from a file descriptor, or a combination of both.

Note: All timestamps are as seconds since the epoch. (01 Jan 1970, 00:00 GMT)

GASS Server Activation and Deactivation

GASS uses standard Globus module activation and deactivation. Before any GASS server functions are called, the following function must be called:

globus_module_activate(GLOBUS_GASS_SERVER_MODULE);

This function returns GLOBUS_SUCCESS if GASS was successfully initialized, and you are therefore allowed to subsequently call GASS server functions. Otherwise, and error code is returned, and GASS server functions should not be subsequently called. This function may be called multiple times.

To deactivate GASS cache, the following function must be called:

globus_module_deactivate(GLOBUS_GASS_SERVER_MODULE);

This function should be called once for each time the GASS server was activated.

GASS Server Functions

int
globus_gass_server_listen(
    unsigned short *port,
    globus_gass_server_get_callback_t get_callback,
    void *get_user_arg,
    globus_gass_server_put_callback_t put_callback,
    void *put_user_arg)

Create a port and listen on it for get and put requests made by a globus_gass_client using an x-gass URL.

If *port is set to 0 when this function is called, then an anonymous port is used, and the port is returned in *port. Otherwise, the port specified by *port is used.

The get_callback and put_callback arguments, if not GLOBUS_GLOBUS_GASS_NULL, specify functions to call when a globus_gass_client_get or globus_gass_client_put request is made to this server, respectively. The behavior of each of these callbacks is described below.

This function returns GLOBUS_GLOBUS_GASS_SUCCESS if it is successful, otherwise a non-zero error code.

In single threaded code, nexus_poll() or nexus_cond_wait() should be called frequently to service requests.

typedef int
(*globus_gass_server_get_callback_t)(
void *get_user_arg,
char *url,
globus_gass_server_get_request_t *request,
unsigned long *timestamp,
unsigned long *total_length)

When a get request is first made, this callback will be called with a get request structure for this request, which should be passed to one or more subsequent globus_gass_server_get_request_*() calls to supply the data, and globus_gass_server_get_request_done() to cleanup and free the structure.

If this callback returns a value other than GLOBUS_SUCCESS, the globus_gass_client get request will fail with a GLOBUS_GLOBUS_GASS_REQUEST_SERVER_FAILURE and its failure_code set to the value returned by this function.

If this callback returns GLOBUS_SUCCESS, this request structure must be subsequently freed by calling globus_gass_server_get_request_done(). It should also set *timestamp to the file's timestamp or GLOBUS_GLOBUS_GASS_UNKNOWN_TIMESTAMP if unknown; and set *total_length to the length of the data that will be supplied for this request, or GLOBUS_GLOBUS_GASS_UNKNOWN_LENGTH if unknown.

The following fields can be accessed directly from the request structure:

request->status (int)

GLOBUS_GLOBUS_GASS_REQUEST_PENDING
The request is still in progress.

GLOBUS_GLOBUS_GASS_REQUEST_SYSTEM_FAILURE
The request failed due to a system failure (e.g. the server died).
*The failure_code contains the reason for the failure.

GLOBUS_GLOBUS_GASS_REQUEST_SERVER_FAILURE
The request failed due to an explicit failure call by the GASS server.
*The failure_code contains the reason for the failure, as supplied by the GASS server.

GLOBUS_GLOBUS_GASS_REQUEST_CLIENT_FAILURE
The request failed due to an explicit failure call by the GASS client.
*The failure_code contains the reason for the failure, as supplied by the GASS client.

GLOBUS_GLOBUS_GASS_REQUEST_DONE
The request has completed successfully.

request->failure_code (int)

Set to a failure code when request->status is GLOBUS_GLOBUS_GASS_REQUEST_*_FAILURE.

request->total_length (unsigned long)

Total length of the data sent.

request->outstanding (int)

The number of globus_gass_server_get_request_fd() and globus_gass_server_get_request_memory() calls that are currently outstanding for this request.

request->subject (char *)

The subject (i.e. globus user name) of the client that made this request. It is NULL if the subject is not known.

request->user_pointer (void *)

A pointer that can be used by the user for any purpose.

int
globus_gass_server_get_request_fd(
    globus_gass_server_get_request_t *request,
    int fd,
    unsigned long block_size,
    unsigned long max_length,
    globus_bool_t last_data,
    globus_gass_server_get_request_fd_done_t callback)

Read data from the file descriptor fd and send it for the get request. If block_size!=0, then this specifies a preferred block size that GASS should use when reading from the file descriptor. If max_length==GLOBUS_GLOBUS_GASS_LENGTH_UNKNOWN, then read and send until end-of-file is reached on the file descriptor. Otherwise, read and send send max_length bytes or until end-of-file, whichever comes first.

If last_data==GLOBUS_TRUE, then this is the last globus_gass_server_get_request_*() function that will be called for this request.

For a single request, calls to globus_gass_server_get_request_done() and globus_gass_server_get_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_server_get_callback_t(). If the return value is GLOBUS_GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_server_get_request_fd_done_t)(
globus_gass_server_get_request_t *request,
int fd,
unsigned long send_length)

This function is called as a result of completion of a globus_gass_server_get_request_fd() request.

send_length is actual length of the portion of data sent for this globus_gass_server_get_request_fd() call.

The request->status field is set to the current status of the request, as described in globus_gass_server_get_callback_t(). A value of GLOBUS_GLOBUS_GASS_REQUEST_PENDING implies that subsequent calls to globus_gass_server_get_request_fd() and/or globus_gass_server_get_request_memory()should be made to receive the remainder of the request's data.

Notes:

send_length may be greater than 0 even if request->status is GLOBUS_GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_server_get_request_fd() is outstanding after the request fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the number of currently outstanding requests.

int
globus_gass_server_get_request_memory(
    globus_gass_server_get_request_t *request,
    globus_byte_t *buffer,
    unsigned long buffer_length,
    globus_bool_t last_data,
    globus_gass_server_get_request_memory_done_t callback)

Send buffer_length bytes of data from the memory buffer for the get request.

If last_data==GLOBUS_TRUE, then this is the last globus_gass_server_get_request_*() function that will be called for this request.

For a single request, calls to globus_gass_server_get_request_fd() and globus_gass_server_get_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_server_get_callback_t(). If the return value is GLOBUS_GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_server_get_request_memory_done_t)(
globus_gass_server_get_request_t *request,
globus_byte_t *buffer,
unsigned long send_length)

This function is called as a result of completion of a globus_gass_server_get_request_memory() request.

send_length is actual length of the portion of data sent for this globus_gass_server_get_request_memory() call.

The request->status field is set to the current status of the request, as described in globus_gass_server_get_callback_t(). A value of GLOBUS_GLOBUS_GASS_REQUEST_PENDING implies that subsequent calls to globus_gass_server_get_request_fd() and/or globus_gass_server_get_request_memory() should be made to receive the remainder of the request's data.

Notes:

send_length may be greater than 0 even if request->status is GLOBUS_GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_server_get_request_fd() is outstanding after the request fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the
number of currently outstanding requests.

int
globus_gass_server_get_request_fail(
    globus_gass_server_get_request_t *request,
    globus_gass_server_get_request_fail_t fail_callback,
       int failure_code)

Abort the get request. Both the GASS client and server will be notified of the failure by setting their request->status to GLOBUS_GLOBUS_GASS_REQUEST_SERVER_FAILURE, and the request->failure_code to the value passed in the failure_code argument.

globus_gass_server_get_request_done() must still be called after globus_gass_server_get_request_fail() is called. If there are any outstanding globus_gass_server_get_request_fd() or globus_gass_server_get_request_memory() calls, their callbacks will be performed immediately.

typedef void
(*globus_gass_server_get_request_fail_t) (
globus_gass_server_get_request_t *);

int
globus_gass_server_get_request_done(
globus_gass_server_get_request_t *request)

Complete and cleanup the request that was started by a previous call to globus_gass_server_get_callback_t().

If a previous globus_gass_server_get_request_fd() or globus_gass_server_get_request_memory() call was not called with last_data==GLOBUS_TRUE, then this function implies that there is no more data to get, and the request should complete normally.

typedef int
(*globus_gass_server_put_callback_t)(
void *user_arg,
char *url,
globus_gass_server_put_request_t *request)

When a put request is first made, this callback will be called with a put request structure for this request, which should be passed to one or more subsequent globus_gass_server_put_request_*() calls to retrieve the data, and globus_gass_server_put_request_done() to cleanup and free the structure.

If this callback returns a value other than GLOBUS_SUCCESS, the globus_gass_client put request will fail with a GLOBUS_GLOBUS_GASS_REQUEST_SERVER_FAILURE and its failure_code set to the value returned by this function.

If this callback returns GLOBUS_SUCCESS, this request structure must be subsequently freed by calling globus_gass_server_put_request_done().

The following fields can be accessed directly from the request structure:

request->status (int)

GLOBUS_GLOBUS_GASS_REQUEST_PENDING
The request is still in progress.

GLOBUS_GLOBUS_GASS_REQUEST_SYSTEM_FAILURE
The request failed due to a system failure (e.g. the server died).
*The failure_code contains the reason for the failure.

GLOBUS_GLOBUS_GASS_REQUEST_SERVER_FAILURE
The request failed due to an explicit failure call by the GASS server.
*The failure_code contains the reason for the failure, as supplied by the GASS server.

GLOBUS_GLOBUS_GASS_REQUEST_CLIENT_FAILURE
The request failed due to an explicit failure call by the GASS client.
*The failure_code contains the reason for the failure, as supplied by the GASS client.

GLOBUS_GLOBUS_GASS_REQUEST_DONE
The request has completed successfully.

request->failure_code (int)

Set to a failure code when request->status is GLOBUS_GLOBUS_GASS_REQUEST_*_FAILURE.

request->append (globus_bool_t)

GLOBUS_TRUE if the data should be appended to the end of the specified url. Otherwise, the contents pointed to by the url will be replaced.

request->ack_type (int)

The ack_type, as passed to globus_gass_client_put_request(). It should be used to determine what time argument to pass to globus_gass_server_put_request_done(). Options are:

GLOBUS_GLOBUS_GASS_ACK_NONE
The client is not expecting an ack, so the timestamp argument can be ignored.

GLOBUS_GLOBUS_GASS_ACK_COMPLETE
The client is expecting an ack when all data has been received and handled by the server. The server should wait to call globus_gass_server_put_request_done() until it is ready to ack to the client that this condition has been met. However, the timestamp argument can be ignored.

GLOBUS_GLOBUS_GASS_ACK_TIMESTAMP
The client is expecting an ack when all data has been received and handled by the server. The server should wait to call globus_gass_server_put_request_done() until it is ready to ack to the client that this condition has been met. In addition, the client has requested a timestamp from the server after the data has been received and handled. The server should supply a timestamp in its call to globus_gass_server_put_request_done().

request->outstanding (int)

The number of globus_gass_server_put_request_fd() and globus_gass_server_put_request_memory() calls that are currently outstanding for this request.

request->subject (char *)

The subject (i.e. globus user name) of the client that made this request. It is NULL if the subject is not known.

request->user_pointer (void *)

A pointer that can be used by the user for any purpose.

int
globus_gass_server_put_request_fd(
    globus_gass_server_put_request_t *request,
    int fd,
    unsigned long block_size,
    unsigned long max_length,
    globus_gass_server_put_request_fd_done_t callback)

Receive data for the put request and write it to the file descriptor fd. If block_size!=0, then this specifies a preferred block size that GASS should use when writing to the file descriptor. If max_length==GLOBUS_GLOBUS_GASS_LENGTH_UNKNOWN, then receive the remainder of the request's data. Otherwise, receive max_length bytes, unless fewer bytes remain in the request.

For a single request, calls to globus_gass_server_put_request_fd() and globus_gass_server_put_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_server_put_callback_t(). If the return value is GLOBUS_GLOBUS_GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_server_put_request_fd_done_t)(
globus_gass_server_put_request_t *request,
int fd,
unsigned long receive_length)

This function is called as a result of completion of a globus_gass_server_put_request_fd() request. receive_length is actual length of the portion of data received for this globus_gass_server_put_request_fd() call.

The request->status field is set to the current status of the request, as described in globus_gass_server_put_callback_t(). A value of GLOBUS_GASS_REQUEST_PENDING implies that subsequent calls to globus_gass_server_put_request_fd() and/or globus_gass_server_put_request_memory() should be made to receive the remainder of the request's data.

Notes:

receive_length may be greater than 0 even if request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_server_put_request_fd() is outstanding after the request completes or fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the number of currently outstanding requests.

int
globus_gass_server_put_request_memory(
    globus_gass_server_put_request_t *request,
    globus_byte_t *buffer,
    unsigned long buffer_length,
    unsigned long wait_length,
    globus_gass_server_put_request_memory_done_t callback)

Receive data for the put request and save it into the memory buffer.

If buffer==NULL, then gass will allocate a memory buffer with a maximum size of buffer_length, and a minimum size of wait_length. If buffer_length==GLOBUS_GASS_LENGTH_UNKNOWN, then gass will choose a buffer length of at least wait_length bytes. Buffers that are allocated by gass must be explicitly freed by calling globus_gass_server_put_request_memory_free().

If buffer!=NULL, then buffer_length is the maximum number of bytes that can be read into the buffer.

At least wait_length bytes will then be received into this buffer, unless fewer bytes remain in the request.

For a single request, calls to globus_gass_server_put_request_fd() and globus_gass_server_put_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_server_put_callback_t(). If the return value is GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_server_put_request_memory_done_t)(
globus_gass_server_put_request_t *request,
globus_byte_t *buffer,
unsigned long buffer_length,
unsigned long receive_length)

This function is called as a result of completion of a globus_gass_server_put_request_memory() request.

receive_length is actual length of the portion of data received for this globus_gass_server_put_request_memory() call.

The request->status field is set to the current status of the request, as described in globus_gass_server_put_callback_t(). A value of GLOBUS_GASS_REQUEST_PENDING, implies that subsequent calls to globus_gass_server_put_request_fd() and/or globus_gass_server_put_request_memory() should be made to receive the remainder of the request's data.

Notes:

receive_length may be greater than 0 even if request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_server_put_request_memory() is outstanding after the request completes or fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the
number of currently outstanding requests.

int
globus_gass_server_put_request_memory_free(
globus_gass_server_put_request_t *request,
globus_byte_t *buffer)

Free a memory buffer that was allocated automatically by gass as a result of a call to globus_gass_server_put_request_memory(), and passed to a globus_gass_server_put_request_memory_done_t callback function.

int
globus_gass_server_put_request_fail(
globus_gass_server_put_request_t *request,
int failure_code)

Abort the put request. Both the GASS client and server will be notified of the failure by setting their request->status to GLOBUS_GASS_REQUEST_SERVER_FAILURE, and the request->failure_code to the value passed in the failure_code argument.

globus_gass_server_put_request_done() must still be called after globus_gass_server_put_request_fail() is called. If there are any outstanding globus_gass_server_put_request_fd() or globus_gass_server_put_request_memory() calls, their callbacks will be performed immediately.

typedef void
(*globus_gass_server_put_request_fail_t) (
globus_gass_server_put_request_t *);

int
globus_gass_server_put_request_done(
globus_gass_server_put_request_t *request,
unsigned long timestamp)

Complete and cleanup the request that was started by a previous call to globus_gass_server_put_callback_t().

The timestamp argument can be ignored unless request->status is GLOBUS_GASS_REQUEST_PENDING and request->ack_type is GLOBUS_GASS_ACK_TIMESTAMP.

If request->ack_type is GLOBUS_GASS_ACK_COMPLETE or GLOBUS_GASS_ACK_TIMESTAMP, the server code should wait to call this function until all of the put request data has been handled.