1dd_driver(3)                      globus xio                      dd_driver(3)
2
3
4

NAME

6       dd_driver - Data descriptors globus_xio uses data descriptors to
7       associate meta data with the data being writen or the data read.
8
9       Data descriptors flow into the drivers read and write interface
10       functions by way of the operation structure. If the driver is
11       interested in viewing the data decriptor it can request it from the
12       operation structure via a call to
13       globus_xio_driver_operation_get_data_descriptor() and it can view any
14       driver specific data descriptor via a call to
15       globus_xio_driver_data_descriptor_get_specific(). The driver can modify
16       values in the data descriptor by setting values before passing the
17       request down the stack. Several functions are available to modify the
18       data descriptors. There is no need to 'set()' the data descriptors back
19       into the operation. The functions for manipluating the values in a DD
20       affect the values xio has directly.
21
22       Data descriptors flow back to the driver in the callbacks for the data
23       operations. When calling finished operation on a data operation the
24       driver must pass in a data descriptor. It should get this data
25       descriptor from the io operation callback.
26
27       Life Cycle:
28
29       Passing in a data descriptor: A data descriptor is first created by the
30       globus_xio user. The user can add driver specific data descriptors to
31       it. Once the usre has created and set the attributes on its data
32       descriptor to their liking they pass it into a globus_xio data
33       operation (either read or write). When the data descriptor is passed on
34       globus_xio will make an internal copy of it. It does this by first
35       coping the user the level data descriptor and then walkinging through
36       the list of driver specific data descriptor contianed in to and
37       requesting the the driver make a copy of the driver specific data
38       descriptor. If ever a driver specific data descriptor is NULL
39       globus_xio need not call into its drivers dd_copy function. If ever the
40       user level data descriptor is NULL globus_xio need not deal with the
41       data descriptor functionality at all.
42
43       A data descriptor coming back up the stack Once an io operation reachs
44       the transport driver (the bottom of the stack) it takes on a slightly
45       different role. On the way in it is describing what is requested to be
46       done with the data, on the way out it is describing what has actually
47       been done. Once the transport driver performs the operation it should
48       adjust the data descriptor to reflect what has actually happened (few
49       drivers will need to worry about this). Each driver on the way up can
50       adjust the data descriptor and its driver specific data decriptor. When
51       xio reachs the the top of the stack it calls a user callback. When that
52       callback returns all memory associated with the data descriptor is
53       cleaned up. The interface function
54       globus_xio_driver_data_descriptor_free() is used for this.
55
56
57
58Version 2.8                     Sat Apr 30 2011                   dd_driver(3)