- bookworm 6.6-2
- testing 6.6-2
- unstable 6.6-2
- experimental 6.6-2.1~exp1
globus_xio_driver(3) | globus_xio | globus_xio_driver(3) |
NAME¶
globus_xio_driver - Globus XIO Driver
- Globus XIO Driver.
SYNOPSIS¶
Modules¶
Driver Programming: String options
Driver Programming: String options.
Typedefs¶
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)
Functions¶
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)
Detailed Description¶
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.
Driver Types¶
- Transport driver:
- 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.
- Transform driver:
- 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.
Driver API¶
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.
Quick Start¶
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.
Typical Sequence:¶
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.
- Open
- 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.
- Read/Write
- 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.
- Close
- 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.
Globus XIO Attributes¶
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:
- globus_xio_driver_attr_init_t
- globus_xio_driver_attr_copy_t
- globus_xio_driver_attr_cntl_t
- globus_xio_driver_attr_destroy_t
Pointers to these functions are associated with the driver by calling globus_xio_driver_set_attr
Advanced Driver Programming¶
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.
- Read Ahead
- 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.
Typedef Documentation¶
typedef globus_result_t(* globus_xio_driver_attr_cntl_t) (void *driver_attr, int cmd, va_list ap)¶
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
cmd An integer representing what functionality the user is requesting.
ap variable arguments. These are determined by the driver and the value of cmd.
typedef globus_result_t(* globus_xio_driver_attr_copy_t) (void **dst, void *src)¶
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.
typedef globus_result_t(* globus_xio_driver_attr_destroy_t) (void *driver_attr)¶
Destroy the driver attr.
Clean up all resources associate with the attr.
typedef globus_result_t(* globus_xio_driver_attr_init_t) (void **out_driver_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.
typedef void(* globus_xio_driver_callback_t) (globus_xio_operation_t op, globus_result_t result, void *user_arg)¶
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
result The result of the requested data operation
user_arg The user pointer that is threaded through to the callback.
typedef globus_result_t(* globus_xio_driver_close_t) (void *driver_specific_handle, void *driver_attr, globus_xio_operation_t op)¶
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_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.
typedef void(* globus_xio_driver_data_callback_t) (globus_xio_operation_t op, globus_result_t result, globus_size_t nbytes, void *user_arg)¶
Data Callback interface
This is the function signature of read and write operation
callbacks.
Parameters
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.
typedef globus_result_t(* globus_xio_driver_handle_cntl_t) (void *handle, int cmd, va_list ap)¶
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.
typedef globus_result_t(* globus_xio_driver_link_destroy_t) (void *driver_link)¶
destroy a link
The driver should clean up all resources associated with the link when this function is called.
Parameters
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)¶
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
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().
typedef globus_result_t(* globus_xio_driver_server_accept_t) (void *driver_server, globus_xio_operation_t op)¶
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
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.
typedef globus_result_t(* globus_xio_driver_server_cntl_t) (void *driver_server, int cmd, va_list ap)¶
Query a server for information.
This function allows a user to request information from a driver specific server handle.
Parameters
cmd An integer telling the driver what operation to preform on this server handle.
ap variable args.
typedef globus_result_t(* globus_xio_driver_server_destroy_t) (void *driver_server)¶
destroy a server.
When this function is called the driver should free up all resources associated with a server.
Parameters
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)¶
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
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
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. This is called when a user opens a handle.
Parameters
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.
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. This is called when a user opens a handle.
Parameters
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.
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)¶
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
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().
Function Documentation¶
globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)¶
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
Returns
void globus_xio_driver_finished_accept (globus_xio_operation_t op, void * driver_link, globus_result_t result)¶
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
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
void globus_xio_driver_finished_close (globus_xio_operation_t op, globus_result_t result)¶
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
result Return status of the completed operation
void globus_xio_driver_finished_open (void * driver_handle, globus_xio_operation_t op, globus_result_t result)¶
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
op The requested open operation that has completed.
result Return status of the completed operation
void globus_xio_driver_finished_read (globus_xio_operation_t op, globus_result_t result, globus_size_t nread)¶
Finished Read
This function is called to signal globus_xio that the requested read operation has been completed.
Parameters
result Return status of the completed operation
nread The number of bytes read
void globus_xio_driver_finished_write (globus_xio_operation_t op, globus_result_t result, globus_size_t nwritten)¶
Finished Write
This function is called to signal globus_xio that the requested write operation has been completed.
Parameters
result Return status of the completed operation
nwritten The number of bytes written
globus_result_t globus_xio_driver_handle_cntl (globus_xio_driver_handle_t handle, globus_xio_driver_t driver, int cmd, ...)¶
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
globus_result_t globus_xio_driver_merge_operation (globus_xio_operation_t top_op, globus_xio_operation_t bottom_op)¶
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
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)
globus_result_t globus_xio_driver_operation_create (globus_xio_operation_t * operation, globus_xio_driver_handle_t handle)¶
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
handle The initialized handle representing the user handle from which the operation will be created.
globus_bool_t globus_xio_driver_operation_is_blocking (globus_xio_operation_t operation)¶
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.
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. 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
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.
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)¶
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
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.
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)¶
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
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.
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)¶
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
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.
void globus_xio_driver_set_eof_received (globus_xio_operation_t op)¶
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
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. 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
server_pre_init_func Function to call prior to creating a server
Return values
GLOBUS_XIO_ERROR_PARAMETER Invalid parameter
Author¶
Generated automatically by Doxygen for globus_xio from the source code.
Tue Jul 5 2022 | Version 6.6 |