NAME
Driver Programming -
The set of interface functions that the driver author must implement to
create a driver and the functions to assist in the creation.
Typedefs
typedef void(* globus_xio_driver_callback_t )(globus_xio_operation_t
op, globus_result_t result, void *user_arg)
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 *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)
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)
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_handle, void *driver_attr, globus_xio_operation_t op)
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_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 *user_arg)
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
The set of interface functions that the driver author must implement to
create a driver and the functions to assist in the creation.
Driver attribute functions
If the driver wishes to provide driver specific attributes to the user
it must implement the following functions:
globus_xio_driver_attr_init_t globus_xio_driver_attr_copy_t
globus_xio_driver_attr_cntl_t globus_xio_driver_attr_destroy_t
Typedef Documentation
typedef void(* globus_xio_driver_callback_t)(globus_xio_operation_t op,
globus_result_t result, void *user_arg)
callback interface
This is the function signature of callbacks for the
globus_xio_driver_open/close(). 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.
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:
op The operation structure associated with the read or write
operation request. The driver should call the approriate 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.
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 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_cntl_t)(void *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 resonsible 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.
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 (pasive opens). In
the tcp driver this function should create a listener.
Parameters:
op An op which should be passed to
globus_xio_driver_server_created. Note, that unlike most
operations, the server is created from the bottom of the stack to
the top.
contact_info This the contact info for the stack below this driver.
(entries will always be NULL for the transport driver)
driver_attr A server attr if the user specified any driver specific
attributes. This may be NULL.
Returns:
Returning GLOBUS_SUCCESS for this means that ‘
globus_xio_driver_pass_server_init returned success and the
driver’s server was successfully initialized.
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:
server The server that the driver should clean up.
driver_server The reference to the iunternal server that is being
declaired invaild with this function call.
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 opertunity 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 acepting
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:
driver_server the server handle.
cmd An integer telling the driver what operation to preform on this
server handle.
ap variable args.
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:
driver_link The link to be destroyed.
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 requests to open 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_driver_attr_init_t
interface funstion.
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
op The requested operation. When the driver is finished opening the
handle it uses this structure to signal globus_xio that it has
completed the operation requested. It does this by calling
globus_xio_driver_finished_open()
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)
transport open
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_close_t)(void *driver_handle,
void *driver_attr, globus_xio_operation_t op)
Close an open handle
This is called when a user requests to close a handle. The driver
implemntor should clean up all resources connected to there driver
handle when this function is called.
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 requested operation. When the driver is finished closing the
handle it uses this structure to signal globus_xio that it has
completed the operation requested. It does this by calling
globus_xio_driver_finished_close()
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:
driver_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 fullfilling
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_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:
driver_handle The driver handle to which data should be writen.
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 fullfilling
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_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
References globus_xio_driver_handle_cntl().
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
potientially 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
References globus_xio_driver_finished_accept().
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 intialized 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 wehn the open operation is complete.
user_arg a user pointer that will be threaded through to the
callback.
References globus_xio_driver_pass_open().
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 potientially 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 funstion calls.
op The requested open operation that has completed.
result Return status of the completed operation
References globus_xio_driver_finished_open().
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:
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.
References globus_xio_driver_operation_create().
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 certian optimizations. The function
returns true if the given operation was created via a user call to a
blocking funciton.
globus_result_t globus_xio_driver_pass_close (globus_xio_operation_t op,
globus_xio_driver_callback_t cb, void * user_arg)
Driver API Close
This function will pass a close request down the driver stack. Upon
completion of the close operation globus_xio will call the funciton
pointed to by the cb argument.
Parameters:
op The operation to pass along the driver stack for closing.
cb A pointer to the function to be called once all drivers lower in
the stack have closed.
user_arg A user pointer that will be threaded through to the
callback.
References globus_xio_driver_pass_close().
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:
op The close operation that has completed.
result Return status of the completed operation
References globus_xio_driver_finished_close().
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 funciton pointed to by cb. Finishe 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 specifc 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.
References globus_xio_driver_pass_read().
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:
op The operation structure representing the requested read
operation.
result Return status of the completed operation
nread The number of bytes read
References globus_xio_driver_finished_read().
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:
op The operation structure representing the requested read
operation.
References globus_xio_driver_set_eof_received().
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:
op The operation structure representing the requested read
operation.
Returns:
GLOBUS_TRUE if eof received, GLOBUS_FALSE otherwise.
References globus_xio_driver_eof_received().
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 funciton 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 specifc 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.
References globus_xio_driver_pass_write().
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:
op The operation structure representing the requested write
operation.
result Return status of the completed operation
nwritten The number of bytes written
References globus_xio_driver_finished_write().
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 prestaged 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)
Author
Generated automatically by Doxygen for globus xio from the source code.