NAME
User API Assistance. -
Help understanding the globus_xio api.
Help understanding the globus_xio api.
Stack Constuction.
The driver stack that is used for a given xio handle is constructed
using a globus_xio_stack_t. Each driver is loaded by name and
pushed onto a stack.
stack setup example:
// First load the drivers
globus_xio_driver_load(’tcp’, &tcp_driver);
globus_xio_driver_load(’gsi’, &gsi_driver);
//build the stack
globus_xio_stack_init(&stack);
globus_xio_stack_push_driver(stack, tcp_driver, NULL);
globus_xio_stack_push_driver(stack, gsi_driver, NULL);
Servers
A server data structure provides functionality for passive opens. A
server is initialized and bound to a protocol stack and set of
attributes with the function globus_xio_server_create(). Once a
server is created many ’connections’ can be accepted. Each
connection will result in an intialized handle which can later be
opened.
globus_xio_server_t server;
globus_xio_attr_t attr;
globus_xio_attr_init(&attr);
globus_xio_server_create(&server_handle, attr, stack);
globus_xio_server_accept(&handle, server);
Handle Construction
There are two ways to create a handle. The first is for use as a
client (one that is doing an active open). The function:
globus_xio_handle_create() is used to create such a handle and bind
that handle to a protocol stack.
globus_xio_handle_create(&handle, stack);
The second means of creating a handle is for use as a server (one that
is doing a passive open). This is created by accepting a connection on
a server_handle with the function globus_xio_server_accept() or
globus_xio_server_register_accept().
Mutable attrs can be altered via a call to globus_xio_handle_cntl()
described later.
globus_xio_server_accept(&xio_handle, server_handle);
once a handle is intialized the user can call globus_xio_open() to
begin the open process.
Timeouts
A user can set a timeout value for any io operation. Each IO
operation (open close read write) can have its own timeout value.
If no timeout is set the operation will be allowed to infinitly
block.
When time expires the outstanding operation is canceled. If the
timeout callback for the given operation is not NULL it is called
first to notify the user that the operation timed out and give the
user a chance to ignore that timeout. If canceled, the user will
get the callback they registered for the operation as well, but it
will come with an error indicating that it has been canceled.
It is possiblie that part of an io operation will complete before
the timeout expires. In this case the opperation can still be
canceled. The user will receive there IO callback with and error
set and the length value appropriately set to indicate how much of
the operation completed.
Data Desciptor
The data descriptor ADT gives the user a means of
attaching/extracting meta data to a read or write operation.
Things like offset, out of band message, and other driver specific
meta data are contained in the data descriptor.
Data descriptors are passed to globus_xio in globus_xio_read() and
globus_xio_write(). Within the globus_xio framework it is
acceptable to pass NULL instead of a valid data_descriptor,
ex:
globus_xio_data_descriptor_init(&desc);
globus_xio_data_descriptor_cntl(desc,
tcp_driver,
GLOBUS_XIO_TCP_SET_SEND_FLAGS,
GLOBUS_XIO_TCP_SEND_OOB);
User Attributes
Globus XIO uses a single attribute object for all of its functions.
Attributes give an the user an extenable mechanism to alter default
values which control parameters in an operation.
In most of the globus xio user api functions a user passes an
attribute as a parameter. In many cases the user may ignore the
attribute parameter and just pass in NULL. However at times the
user will wish to tweak the operation. The attribute structure is
used for this tweaking.
There are only three attribute functions. globus_xio_attr_init
globus_xio_attr_cntl and globus_xio_attr_destroy. The init and
destroy functions are very simple and require little explaination.
Before an attribute can be used it must be intialized, and to clean
up all memory associated with it the user must call destroy on it.
The function globus_xio_attr_cntl manipulates values in the
attribute. For more info on it see globus_xio_attr_cntl.
Author
Generated automatically by Doxygen for globus xio from the source code.