XIO: User's Guide

As in all globus programs the first thing that must be done is to activate the globus module by running:

globus_module_activate(GLOBUS_XIO_MODULE); 

Until activated, no globus_xio function calls can be successfully executed.

The next step is to load all the drivers needed to complete the IO operations in which you are interested. Do this with the globus_xio_load_driver()function.

In order to successfully call this function you must know the name of all the drivers you wish to load.

For this example we only want to load the file io driver. The prepackaged file io driver's name is: "file". This driver would be loaded with the following code:

globus_result_t res; 
globus_xio_driver_t driver; 
res = globus_xio_driver_load(&driver, "file");

The driver was successfully loaded if the above function call:

res == GLOBUS_SUCCESS

You can now reference the driver with variable driver.

Now that globus_xio is activated and we have a driver load we need to build a driver stack.

In our example the stack is very simple as it consists of only one driver, the file driver.

The stack is established with the following code (building off of the above code snips):

globus_xio_stack_t stack; 
globus_xio_stack_init(&stack);     
globus_xio_stack_push_driver(stack, driver); 

Now that the stack is created we can open a handle to the file.

There are two ways that a handle can be opened.

1. The first is a passive open. An example of this is a TCP listener. The open is performed passively by waiting for some other entity to act upon it.
   
2. The second is an active open. An active open is the opposite of a passive open. The TCP counter example for this is a connect. The user initiates the open. In our example we shall be performing an active open:

Before opening a handle it must be intialized.

Initializing client side handles

The following illustrates initialization for client side handles:

globus_xio_handle_t handle; 
res = globus_xio_handle_create(&handle, stack);       

Initializing server side handles

Server side handles are a bit more complicated. First we must introduce the data structure globus_xio_server_t. This structure shares many concepts with a TCP listener, mainly that it spawns handles ("connections") as passive open requests are made. If the user wishes to accept a new connection, a call to globus_xio_accept() or globus_xio_register_accept() will initialize a new handle:

globus_xio_server_t server; 
globus_xio_handle_t handle; 
globus_result_t res; 
res = globus_xio_server_create(&server_handle, NULL, stack); 
res = globus_xio_server_accept(&handle, server);

Once the handle is initialized, it should be open in order to perform read and write operations upon it.

If the handle is a client, then a "contact string" is required. This string represents the target that the user wishes to open:

globus_xio_attr_t attr; 
char * contact_string = "file:/etc/groups"; 
globus_xio_attr_init(&attr);
globus_xio_open(xio_handle, contact_string, attr); 
globus_xio_attr_destroy(attr);       

Note: attrs can be used to color behaviors of a handle. For conceptual undertanding at this point they are not important and a user is free to simple pass NULL wherever an attr is required.

Now that you have an open handle to a file, you can

• read data with globus_xio_read()
• write data to it with globus_xio_write().

This may seem like quite a bit of effort for simple reading a file, and it is. However the advantages become clear when exploring the swapping of other drivers.

In the above example it would be trivial to change the IO operations from file IO to TCP, or HTTP, or FTP. All the the user would need to do is change two things:

• the driver name string passed to globus_xio_load_driver()
• and the contact string passed to globus_xio_target_init()

This can easily be done at runtime as the program globus_xio_example.c demonstrates.

So the little program globus_xio_example.c has the ability to be any reading client, or server, (HTTP, FTP, TCP, file, etc) as long as the proper drivers are in the LD_LIBRARY_PATH.