.TH "User API Assistance." 3 "Mon Apr 30 2012" "Version 3.3" "globus xio" \" -*- nroff -*-
.ad l
.nh
.SH NAME
User API Assistance. \- 
.br
 Help understanding the globus_xio api\&. 


.br
.PP
\fBStack Constuction\&.\fP
.RS 4
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\&.
.RE
.PP
.PP
.nf
  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);
.fi
.PP
.PP
\fBServers\fP
.RS 4
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 \fBglobus_xio_server_create()\fP\&. Once a server is created many 'connections' can be accepted\&. Each connection will result in an intialized handle which can later be opened\&.
.RE
.PP
.PP
.nf
  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);
.fi
.PP
.PP
\fBHandle Construction\fP
.RS 4
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: \fBglobus_xio_handle_create()\fP is used to create such a handle and bind that handle to a protocol stack\&.
.RE
.PP
.PP
.nf
  globus_xio_handle_create(&handle, stack);
.fi
.PP
.PP
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 \fBglobus_xio_server_accept()\fP or \fBglobus_xio_server_register_accept()\fP\&.
.PP
Mutable attrs can be altered via a call to \fBglobus_xio_handle_cntl()\fP described later\&.
.PP
.PP
.nf
  globus_xio_server_accept(&xio_handle, server_handle);
.fi
.PP
.PP
once a handle is intialized the user can call \fBglobus_xio_open()\fP to begin the open process\&.
.PP
\fBTimeouts\fP
.RS 4
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\&.
.br
 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\&.
.br
 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\&.
.RE
.PP
\fBData Desciptor\fP
.RS 4
The data descriptor ADT gives the user a means of attaching/extracting meta data to a read or write operation\&.
.br
 Things like offset, out of band message, and other driver specific meta data are contained in the data descriptor\&.
.br
 Data descriptors are passed to globus_xio in \fBglobus_xio_read()\fP and \fBglobus_xio_write()\fP\&. Within the globus_xio framework it is acceptable to pass NULL instead of a valid data_descriptor,
.RE
.PP
.PP
.nf
  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);
.fi
.PP
.PP
\fBUser Attributes\fP
.RS 4
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\&.
.br
 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\&.
.br
 There are only three attribute functions\&. \fBglobus_xio_attr_init\fP \fBglobus_xio_attr_cntl\fP and \fBglobus_xio_attr_destroy\fP\&. 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\&.
.br
 The function \fBglobus_xio_attr_cntl\fP manipulates values in the attribute\&. For more info on it see \fBglobus_xio_attr_cntl\fP\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus xio from the source code\&.