globus_xio_driver(3) Library Functions Manual globus_xio_driver(3)

globus_xio_driver - Globus XIO Driver


- Globus XIO Driver.


Driver Programming: String options
Driver Programming: String options.


typedef void(* globus_xio_driver_callback_t) (globus_xio_operation_t op, globus_result_t result, void *user_arg)
Open and Close Callback Signature. typedef void(* globus_xio_driver_data_callback_t) (globus_xio_operation_t op, globus_result_t result, globus_size_t nbytes, void *user_arg)
typedef globus_result_t(* globus_xio_driver_attr_init_t) (void **out_driver_attr)
typedef globus_result_t(* globus_xio_driver_attr_copy_t) (void **dst, void *src)
typedef globus_result_t(* globus_xio_driver_attr_destroy_t) (void *driver_attr)
typedef globus_result_t(* globus_xio_driver_attr_cntl_t) (void *driver_attr, int cmd, va_list ap)
typedef globus_result_t(* globus_xio_driver_server_init_t) (void *driver_attr, const globus_xio_contact_t *contact_info, globus_xio_operation_t op)
typedef globus_result_t(* globus_xio_driver_server_destroy_t) (void *driver_server)
typedef globus_result_t(* globus_xio_driver_server_accept_t) (void *driver_server, globus_xio_operation_t op)
typedef globus_result_t(* globus_xio_driver_server_cntl_t) (void *driver_server, int cmd, va_list ap)
typedef globus_result_t(* globus_xio_driver_link_destroy_t) (void *driver_link)
typedef globus_result_t(* globus_xio_driver_transform_open_t) (const globus_xio_contact_t *contact_info, void *driver_link, void *driver_attr, globus_xio_operation_t op)
Open a handle. typedef globus_result_t(* globus_xio_driver_transport_open_t) (const globus_xio_contact_t *contact_info, void *driver_link, void *driver_attr, globus_xio_operation_t op)
Open a handle. typedef globus_result_t(* globus_xio_driver_handle_cntl_t) (void *handle, int cmd, va_list ap)
typedef globus_result_t(* globus_xio_driver_close_t) (void *driver_specific_handle, void *driver_attr, globus_xio_operation_t op)
Close a handle. typedef globus_result_t(* globus_xio_driver_read_t) (void *driver_specific_handle, const globus_xio_iovec_t *iovec, int iovec_count, globus_xio_operation_t op)
typedef globus_result_t(* globus_xio_driver_write_t) (void *driver_specific_handle, const globus_xio_iovec_t *iovec, int iovec_count, globus_xio_operation_t op)


globus_result_t globus_xio_driver_set_server_pre_init (globus_xio_driver_t driver, globus_xio_driver_server_init_t server_pre_init_func)
Server Pre-Init. globus_result_t globus_xio_driver_handle_cntl (globus_xio_driver_handle_t handle, globus_xio_driver_t driver, int cmd,...)
void globus_xio_driver_finished_accept (globus_xio_operation_t op, void *driver_link, globus_result_t result)
globus_result_t globus_xio_driver_pass_open (globus_xio_operation_t op, const globus_xio_contact_t *contact_info, globus_xio_driver_callback_t cb, void *user_arg)
void globus_xio_driver_finished_open (void *driver_handle, globus_xio_operation_t op, globus_result_t result)
globus_result_t globus_xio_driver_operation_create (globus_xio_operation_t *operation, globus_xio_driver_handle_t handle)
globus_bool_t globus_xio_driver_operation_is_blocking (globus_xio_operation_t operation)
globus_result_t globus_xio_driver_pass_close (globus_xio_operation_t op, globus_xio_driver_callback_t cb, void *callback_arg)
Pass the close operation down the driver stack. void globus_xio_driver_finished_close (globus_xio_operation_t op, globus_result_t result)
globus_result_t globus_xio_driver_pass_read (globus_xio_operation_t op, globus_xio_iovec_t *iovec, int iovec_count, globus_size_t wait_for, globus_xio_driver_data_callback_t cb, void *user_arg)
void globus_xio_driver_finished_read (globus_xio_operation_t op, globus_result_t result, globus_size_t nread)
void globus_xio_driver_set_eof_received (globus_xio_operation_t op)
globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)
globus_result_t globus_xio_driver_pass_write (globus_xio_operation_t op, globus_xio_iovec_t *iovec, int iovec_count, globus_size_t wait_for, globus_xio_driver_data_callback_t cb, void *user_arg)
void globus_xio_driver_finished_write (globus_xio_operation_t op, globus_result_t result, globus_size_t nwritten)
globus_result_t globus_xio_driver_merge_operation (globus_xio_operation_t top_op, globus_xio_operation_t bottom_op)

Globus XIO Driver.

Globus XIO introduces a notion of a driver stack to its API. Within globus_xio every I/O operation must occur on a globus_xio handle. Associated with each handle is a stack of drivers. A driver is a modulular piece of code that implements the globus_xio driver interface. The purpose of a driver is manipulate data passed in by the user in someway. Each driver in a stack will serve its own unique purpose.

I/O operations pass from driver to driver, starting at the top of the stack and ending at the bottom. When the bottom layer driver finishes with the operation it signals globus_xio that it has completed.
Completion notification then flows up to the top of the driver stack.

A transport driver is one that is responsible for data communication. For example, a TCP or UDP driver would transmit data via network sockets, or a file driver would write data to a file.

There must be exactly one transport driver in a stack, at its bottom. A transport driver never passes an operation to another driver in the stack. Instead, this type of driver relies on globus_xio system functions to implement data operations.

A transform driver is any intermediate driver in the stack. A transform driver relies on some other drivers on the driver stack to perform the data transport operation. An example of a transform driver would one which implements a network protocol such as http. This driver would frame and parse messages, but would rely on other drivers in the XIO stack.

This allows additional transforms to happen in the XIO stack, such as layering the http protocol on top of an SSL protocol driver before transmitting the data via TCP.

The Globus XIO Driver API is a set of functions and interfaces to allow a developer to create an XIO driver. To create a driver the user must implement all of the interface functions in the driver specification. There is also a set of functions provided to assist the driver author in implementing a driver.

For basic driver needs, the developer will have to pay attention to a few structures and concepts.

globus_xio_operation_t
This structure represents a request for an operation. If the driver can service the operation it does so and the calls the appropriate finished function. If the driver cannot completely service the operation it can pass it to the next driver in the stack. As soon as the operation structure is either finished or passed it is no longer valid for use in any other function.
globus_xio_driver_handle_t
A globus_xio_driver_handle_t represents an open handle to the driver stack for XIO. The driver obtains a driver_handle by calling globus_xio_operation_get_driver_handle(). The driver_handle allows the user to do some complex things that will be described later.

Here is a typical sequence of events for a globus_xio transform driver. All operations are initiated either by the application calling a function in the Globus XIO API, or from a driver above the transform driver in the stack passing an operation to this driver.

XIO calls the globus_xio_driver_transform_open_t function of the driver, passing it the operation and, in the case of a passive open, the link from a server accept. The driver typically allocates a private data structure containing the state it wishes to associate with this handle, and passes this along with a callback function pointer to globus_xio_driver_pass_open(). This allows the other drivers in the XIO stack to continue to process the operation.

After the lower drivers in the stack have completed processing the open, they will call globus_xio_driver_finished_open(), which will in turn call the callback function which the driver passed as a parameter to globus_xio_driver_pass_open(). The driver then does any post-open operation needed, and then finishes the operation by calling globus_xio_driver_finished_open(), passing the private state data as the driver_handle parameter. This state data will be passed to future operation implementations done with this handle.

XIO calls the driver's globus_xio_driver_read_t or globus_xio_driver_write_t function with an operation as a parameter and the state date from the globus_xio_driver_finished_open() call. The driver then transforms the data if necessary and then calls the globus_xio_driver_pass_read() or globus_xio_driver_pass_write() which passes the operation down the XIO driver stack. When the driver below it on the XIO stack calls globus_xio_driver_finished_read() or globus_xio_driver_finished_write(), the callback which was passed is invoked. In that callback, the driver should itself call globus_xio_driver_finished_read() or globus_xio_driver_finished_write() to indicate completion.
XIO calls the close interface function, passing an operation and the private driver state. The driver will call globus_xio_driver_pass_close() passing it the operation. When the close callback is received the driver calls globus_xio_driver_finished_close() passing it the operation. At this point, the driver typically frees its private data, as the handle is no longer valid.

Attributes provide a way to pass additional metadata to driver operations. Most Globus XIO API functions include an attribute parameter. Each driver implements its own set of attribute handling function. To implement attributes, a driver must provide functions of these types:

Pointers to these functions are associated with the driver by calling globus_xio_driver_set_attr

The typical driver implementation is describe above. However globus_xio allows driver authors to do more advanced things such as initiating operations on their own.

Once a handle is open, a driver can create operation structures from it. A driver can then request I/O from the driver stack before it receives a call to its own I/O interface functions, implementing read-ahead functionality. This can be done as follows:

1.
Obtain a driver handle from the open operation by calling globus_xio_operation_get_driver_handle()
2.
Create an operation by calling globus_xio_driver_operation_create() and pass it the driver_handle from the previous step
3.
call globus_xio_driver_pass_read() using this operation. When the read callback is received, the driver saves the returned data in its private data and then calls globus_xio_driver_finished_read() on the operation.
4.
When XIO calls the driver's read interface function, the driver can immediately call globus_xio_driver_finished_read() function after updating the iovec structure with the data it had previously read.

get or set information in an attr.

The cmd parameter determines what functionality the user is requesting. The driver is responsible for providing documentation to the user on all the possible values that cmd can be.

Parameters

driver_attr The driver specific attr, created by globus_xio_driver_attr_init_t.
cmd An integer representing what functionality the user is requesting.
ap variable arguments. These are determined by the driver and the value of cmd.

Copy a driver attr.

When this function is called the driver will create a copy of the attr in parameter src and place it in the parameter dst.

Destroy the driver attr.

Clean up all resources associate with the attr.

Create a driver specific attribute.

The driver should implement this function to create a driver specific attribute and return it via the out_attr parameter.

Open and Close Callback Signature. This is the function signature of callbacks for the globus_xio_pass_open() and globus_xio_pass_close() functions.

Parameters

op The operation structure associated with the open or the close requested operation. The driver should call the appropriate finished operation to clean up this structure.
result The result of the requested data operation
user_arg The user pointer that is threaded through to the callback.

Close a handle. This closes a handle. Driver implementations should pass the close to the other drivers in the stack by calling globus_xio_pass_close().

In the close callback, the driver should clean up the data associated with driver_handle.

Parameters

driver_specific_handle The driver handle to be closed.
driver_attr A driver specific attr which may be used to alter how a close is performed (e.g. caching drivers)
op The open operation. When the driver is finished opening the handle, it passes this to globus_xio_driver_finished_close() to return status up the driver stack to the application.

Data Callback interface

This is the function signature of read and write operation callbacks.

Parameters

op The operation structure associated with the read or write operation request. The driver should call the appropriate finished operation when it receives this operation.
result The result of the requested data operation
nbytes the number of bytes read or written
user_arg The user pointer that is threaded through to the callback.

this call must return an GLOBUS_XIO_ERROR_COMMAND error for unsupported command numbers. (use GlobusXIOErrorInvalidCommand(cmd))

Drivers that have reason to support the commands listed at globus_xio_handle_cmd_t should accept the xio generic cmd numbers and their driver specific command number. Do NOT implement those handle cntls unless you really are the definitive source.

destroy a link

The driver should clean up all resources associated with the link when this function is called.

Parameters

driver_link The link to be destroyed.

Read data from an open handle.

This function is called when the user requests to read data from a handle. The driver author shall implement all code needed to for there driver to complete a read operations.

Parameters

driver_specific_handle The driver handle from which data should be read.
iovec An io vector pointing to the buffers to be read into.
iovec_count The number if entries in the io vector.
op The requested operation. When the driver is finished fulfilling the requested read operation it must use this structure to signal globus_xio that the operation is completed. This is done by calling globus_xio_driver_finished_operation().

Accept a server connection

The driver developer should implement this function if their driver handles server operations. Once the accept operation completes, the connection is established. The user still has an opportunity to open the link or destroy it. They can query the link for additional information on which to base the decision to open.

Parameters

driver_server The server object from which the link connection will be accepted.
op The requested operation. When the driver is finished accepting the server connection it uses this structure to signal globus_xio that it has completed the operation.

Query a server for information.

This function allows a user to request information from a driver specific server handle.

Parameters

driver_server the server handle.
cmd An integer telling the driver what operation to preform on this server handle.
ap variable args.

destroy a server.

When this function is called the driver should free up all resources associated with a server.

Parameters

driver_server The reference to the internal server that is being declared invalid with this function call.

Initialize a server object

The driver developer should implement this function if their driver handles server operations (passive opens). In the TCP driver this function creates a TCP socket and calls listen() on it. Unlike all other XIO driver implementation functions, the globus_xio_server_create() function begins at the bottom (transport driver) of the stack, and the globus_xio_driver_pass_server_init() acts like a finished() operation.

Parameters

driver_attr A driver-specific attribute. This may be NULL.
contact_info Contact information from the stack below this driver. This is NULL for the transport driver.
op An op which must be passed to globus_xio_driver_pass_server_init() to pass the server contact information up the XIO driver stack.

Returns

Returning GLOBUS_SUCCESS for this means that globus_xio_driver_pass_server_init returned success and the driver's server-specific data is initialized.

Open a handle. This is called when a user opens a handle.

Parameters

contact_info Contains information about the requested resource. Its members may all be null (especially when link is not null). XIO will destroy this contact info upon return from the interface function
driver_link Comes from server accept. Used to link an accepted connection to an xio handle. XIO will destroy this object upon the return of this interface call.
driver_attr A attribute describing how to open. This points to a piece of memory created by the globus_xio_driver_attr_init_t interface function.
op The open operation. When the driver is finished opening the handle, it passes this to globus_xio_driver_finished_open() to return status up the driver stack to the application.

Open a handle. This is called when a user opens a handle.

Parameters

contact_info Contains information about the requested resource. Its members may all be null (especially when link is not null). XIO will destroy this contact info upon return from the interface function
driver_link Comes from server accept. Used to link an accepted connection to an xio handle. XIO will destroy this object upon the return of this interface call.
driver_attr A attribute describing how to open. This points to a piece of memory created by the globus_xio_driver_attr_init_t interface function.
op The open operation. When the driver is finished opening the handle, it passes this to globus_xio_driver_finished_open() to return status up the driver stack to the application.

Write data from an open handle.

This function is called when the user requests to write data to a handle. The driver author shall implement all code needed to for there driver to complete write operations.

Parameters

driver_specific_handle The driver handle to which data should be written.
iovec An io vector pointing to the buffers to be written.
iovec_count The number if entries in the io vector.
op The requested operation. When the driver is finished fulfilling the requested read operation it must use this structure to signal globus_xio that the operation is completed. This is done by calling globus_xio_driver_finished_operation().

EOF state checking

This function is used by drivers that allow multiple outstanding reads at a time. It can only be called on behalf of a read operation (while in the read interface call or the pass_read callback).

Typical use for this would be to hold a driver specific lock (the same one used when calling globus_xio_driver_set_eof_received()) and call this to see if an EOF has been received. If so, the operation should immediately be finished with an EOF error (do not return an EOF error).

This call will typically only be used in the read interface call.

Parameters

op The operation structure representing the requested read operation.

Returns

GLOBUS_TRUE if EOF received, GLOBUS_FALSE otherwise.

Driver API finished accept

This function should be called to signal globus_xio that it has completed the accept operation requested of it. It will free up resources associated with the accept_op and potentially cause xio to pop the signal up the driver stack.

Parameters

op The requested accept operation that has completed.
driver_link This is the initialized driver link that is that will be passed to the open interface when this handle is opened.
result Return status of the completed operation

Driver API finished_close

The driver calls this function after completing a close operation on a driver_handle. Once this function returns the driver_handle is no longer valid.

Parameters

op The close operation that has completed.
result Return status of the completed operation

Driver API finished open

This function should be called to signal globus_xio that it has completed the open operation requested of it. It will free up resources associated with the op and potentially cause xio to pop the signal up the driver stack.

Parameters

driver_handle The driver specific handle pointer that will be passed to future interface function calls.
op The requested open operation that has completed.
result Return status of the completed operation

Finished Read

This function is called to signal globus_xio that the requested read operation has been completed.

Parameters

op The operation structure representing the requested read operation.
result Return status of the completed operation
nread The number of bytes read

Finished Write

This function is called to signal globus_xio that the requested write operation has been completed.

Parameters

op The operation structure representing the requested write operation.
result Return status of the completed operation
nwritten The number of bytes written

Touch driver specific information in a handle object.

pass the driver to control a specific driver pass NULL for driver for XIO specific cntls pass GLOBUS_XIO_QUERY for driver to try each driver (below current) in order

Finishes an operation and merge two op structures. (XXX not implemented yet)

This function will join to operations together and signal globus_xio that it has completed. This is an advanced function. Most drivers will not require its use. This function takes an operation that was created by this driver and passed on to drivers lower on the stack and an operation that came in on the interface function (that has seen the top half of the stack) and joins them together. The purpose of this function is to join data descriptors that were pre-staged and cached with those that have later come in at the users request. See the read ahead doc for more information.

Parameters

top_op The operation that has seen the top part of the driver stack.
bottom_op The operation that has seen the bottom part of the driver stack.

(result is always success in this case. if there is an error, use the other finish() call)

Driver API Create Operation

This function will create an operation from an initialized handle This operation can then be used for io operations related to the handle that created them.

Parameters

operation The operation to be created. When this function returns this structure will be populated and available for use for the driver.
handle The initialized handle representing the user handle from which the operation will be created.

Is Operation blocking.

If the operation is blocking the driver developer may be able to make certain optimizations. The function returns true if the given operation was created via a user call to a blocking function.

Pass the close operation down the driver stack. This function will pass a close request down the driver stack. Upon completion of the close operation globus_xio will call the function pointed to by the cb parameter.

Parameters

op The close operation.
cb A pointer to the function to be called once all drivers lower in the stack have closed.
callback_arg A pointer that will be passed to the callback.

Driver API Open

This function will pass an open request down the driver stack. Upon completion of the open operation globus_xio will call the cb function, at which point the handle structure will be initialized and available for use.

As soon as the function returns the handle is valid for creating other operations.

Parameters

op The operation from which the handle will be established. This parameter is used to determine what drivers are in the stack and other such information.
contact_info The contact info describing the resource the driver below should open. This will normally be the same contact info that was passed in on the open interface.
cb The function to be called when the open operation is complete.
user_arg a user pointer that will be threaded through to the callback.

Driver read

This function passes a read operation down the driver stack. After this function is called the op structure is no longer valid. However when the driver stack finishes servicing the read request it will pass a new operation structure in the function pointed to by cb. Finish read can be called on the new operation received.

Parameters

op The operation structure representing this requested io operation.
iovec A pointer to the array of iovecs.
iovec_count The number of iovecs in the array.
wait_for The minimum number of bytes to read before returning. if a driver has no specific requirement, he should use the user's request available via GlobusXIOOperationMinimumRead(op)
cb The function to be called when the operation request is completed.
user_arg A user pointer that will be threaded through to the callback.

Driver write

This function passes a write operation down the driver stack. After this function is called the op structure is no longer valid. However when the driver stack finishes servicing the write request it will pass a new operation structure in the function pointed to by cb. Finished write can be called on the new operation received.

Parameters

op The operation structure representing this requested io operation.
iovec A pointer to the array of iovecs.
iovec_count The number of iovecs in the array.
wait_for The minimum number of bytes to write before returning. If a driver has no specific requirement, he should use the user's request available via GlobusXIOOperationMinimumWrite(op)
cb The function to be called when the operation request is completed.
user_arg A user pointer that will be threaded through to the callback.

EOF state manipulation

This function is used by drivers that allow multiple outstanding reads at a time. It can only be called on behalf of a read operation (while in the read interface call or the pass_read callback).

Typical use for this would be to hold a driver specific lock and call this when an internal EOF has been received. The read operation this is called on behalf of must be finished with an EOF error or the results are undefined.

In general, you should not have an EOF flag in your driver. Use this call and globus_xio_driver_eof_received() instead. This is necessary to support XIO's automatic EOF resetting. If your driver absolutely can not be read after an EOF has been set, then you will need your own EOF flag.

This call will typically only be used just before a finished_read() call.

Parameters

op The operation structure representing the requested read operation.

Server Pre-Init. This function adds a callback to a driver that will be called before a server handle is created by XIO. This function has the same signature as the server_init_func in the driver, but is always called with a NULL contact string. There is no support for calling a pass() or finished() function for this interface. It may inspect and modify its attributes and operation, but can not directly return any data or set a driver-specific server handle value. If this function returns an error result, the server create will be aborted.

Parameters

driver Driver to associate the function with
server_pre_init_func Function to call prior to creating a server

Return values

GLOBUS_SUCCESS Success
GLOBUS_XIO_ERROR_PARAMETER Invalid parameter

Generated automatically by Doxygen for globus_xio from the source code.

Version 6.6 globus_xio