driver_pgm

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



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.



Version 2.8                       13 Feb 2010            Driver Programming(3)