dd_driver(3) globus xio dd_driver(3)NAME
dd_driver - Data descriptors globus_xio uses data descriptors to associate meta data with the data being writen or the data read.
Data descriptors flow into the drivers read and write interface functions by way of the operation structure. If the driver is interested in
viewing the data decriptor it can request it from the operation structure via a call to globus_xio_driver_operation_get_data_descriptor()
and it can view any driver specific data descriptor via a call to globus_xio_driver_data_descriptor_get_specific(). The driver can modify
values in the data descriptor by setting values before passing the request down the stack. Several functions are available to modify the
data descriptors. There is no need to 'set()' the data descriptors back into the operation. The functions for manipluating the values in a
DD affect the values xio has directly.
Data descriptors flow back to the driver in the callbacks for the data operations. When calling finished operation on a data operation the
driver must pass in a data descriptor. It should get this data descriptor from the io operation callback.
Life Cycle:
Passing in a data descriptor: A data descriptor is first created by the globus_xio user. The user can add driver specific data descriptors
to it. Once the usre has created and set the attributes on its data descriptor to their liking they pass it into a globus_xio data
operation (either read or write). When the data descriptor is passed on globus_xio will make an internal copy of it. It does this by first
coping the user the level data descriptor and then walkinging through the list of driver specific data descriptor contianed in to and
requesting the the driver make a copy of the driver specific data descriptor. If ever a driver specific data descriptor is NULL globus_xio
need not call into its drivers dd_copy function. If ever the user level data descriptor is NULL globus_xio need not deal with the data
descriptor functionality at all.
A data descriptor coming back up the stack Once an io operation reachs the transport driver (the bottom of the stack) it takes on a
slightly different role. On the way in it is describing what is requested to be done with the data, on the way out it is describing what
has actually been done. Once the transport driver performs the operation it should adjust the data descriptor to reflect what has actually
happened (few drivers will need to worry about this). Each driver on the way up can adjust the data descriptor and its driver specific data
decriptor. When xio reachs the the top of the stack it calls a user callback. When that callback returns all memory associated with the
data descriptor is cleaned up. The interface function globus_xio_driver_data_descriptor_free() is used for this.
Version 3.3 Mon Apr 30 2012 dd_driver(3)
Check Out this Related Man Page
dispatch_read(3) BSD Library Functions Manual dispatch_read(3)NAME
dispatch_read, dispatch_write -- asynchronously read from and write to file descriptors
SYNOPSIS
#include <dispatch/dispatch.h>
void
dispatch_read(int fd, size_t length, dispatch_queue_t queue, void (^handler)(dispatch_data_t data, int error));
void
dispatch_write(int fd, dispatch_data_t data, dispatch_queue_t queue, void (^handler)(dispatch_data_t data, int error)));
DESCRIPTION
The dispatch_read() and dispatch_write() functions asynchronously read from and write to POSIX file descriptors. They can be thought of as
asynchronous, callback-based versions of the fread() and fwrite() functions provided by the standard C library. They are convenience func-
tions based on the dispatch_io_read(3) and dispatch_io_write(3) functions, intended for simple one-shot read or write requests. Multiple
request on the same file desciptor are better handled with the full underlying dispatch I/O channel functions.
BEHAVIOR
The dispatch_read() function schedules an asynchronous read operation on the file descriptor fd. Once the file descriptor is readable, the
system will read as much data as is currently available, up to the specified length, starting at the current file pointer position. The given
handler block will be submitted to queue when the operation completes or an error occurs. The block will be passed a dispatch data object
with the result of the read operation. If an error occurred while reading from the file descriptor, the error parameter to the block will be
set to the appropriate POSIX error code and data will contain any data that could be read successfully. If the file pointer position is at
end-of-file, emtpy data and zero error will be passed to the handler block.
The dispatch_write() function schedules an asynchronous write operation on the file descriptor fd. The system will attempt to write the
entire contents of the provided data object to fd at the current file pointer position. The given handler block will be submitted to queue
when the operation completes or an error occurs. If the write operation completed successfully, the error parameter to the block will be set
to zero, otherwise it will be set to the appropriate POSIX error code and the data parameter will contain any data that could not be written.
CAVEATS
The data object passed to a handler block is released by the system when the block returns. If data is needed outside of the handler block,
it must concatenate, copy, or retain it.
Once an asynchronous read or write operation has been submitted on a file descriptor fd, the system takes control of that file descriptor
until the handler block is executed. During this time the application must not manipulate fd directly, in particular it is only safe to close
fd from the handler block (or after it has returned).
If multiple asynchronous read or write operations are submitted to the same file descriptor, they will be performed in order, but their han-
dlers will only be submitted once all operations have completed and control over the file descriptor has been relinquished. For details on
this and on the interaction with dispatch I/O channels created from the same file descriptor, see FILEDESCRIPTOR OWNERSHIP in
dispatch_io_create(3).
SEE ALSO dispatch(3), dispatch_data_create(3), dispatch_io_create(3), dispatch_io_read(3), fread(3)Darwin December 1, 2010 Darwin