Scroll to navigation

Driver Programming(3) globus xio Driver Programming(3)

NAME

Driver Programming -

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_thandle, globus_xio_driver_tdriver, intcmd, ...)

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_top, void *driver_link, globus_result_tresult)

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_top, const globus_xio_contact_t *contact_info, globus_xio_driver_callback_tcb, 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_top, globus_result_tresult)

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_thandle)

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_toperation)

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_top, globus_xio_driver_callback_tcb, 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_top, globus_result_tresult)

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_top, globus_xio_iovec_t *iovec, intiovec_count, globus_size_twait_for, globus_xio_driver_data_callback_tcb, 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_top, globus_result_tresult, globus_size_tnread)

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_top)

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_top)

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_top, globus_xio_iovec_t *iovec, intiovec_count, globus_size_twait_for, globus_xio_driver_data_callback_tcb, 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_top, globus_result_tresult, globus_size_tnwritten)

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_ttop_op, globus_xio_operation_tbottom_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.
Mon Apr 30 2012 Version 3.3