CDS Protocol Definition

Conforming implementations shall comply with the behaviour defined in this chapter.

Clerk Operation

A clerk performs the following functions:

• discovers the existence of servers for the local cell name space

• formulates requests to be sent to CDS servers for processing, based on calls by the client

• communicates with one or more CDS servers using the transaction protocol

• receives responses from CDS servers to previously issued requests, and returns the results to the clients who issued the calls

• maintains any credentials needed by a client for authentication purposes by CDS servers

• walks a tree of directories that comprise the relevant part of the cell when necessary for processing of a client request

• optionally maintains a cache of recently accessed information.

Solicitation and Clearinghouse Selection

Since the cell's name space database is partitioned and distributed among a number of clearinghouses, the clerk must first decide which clearinghouses are good candidates for being able to process a client request, and then select one of them. The algorithm for choosing a clearinghouse is internal to the implementation of a clerk and how it caches previously received information; only the solicitation protocol for learning about available clearinghouses is specified in this document.

The following assumptions can be made about the location of clearinghouses:

• The clerk only needs to contact one CDS server to be able to find any clearinghouse in the name space.

• All clearinghouses contain a replica of the cell root; therefore any clearinghouse is able to provide location hints for any other clearinghouses that are always registered in the root directory.

Regardless of the details of its particular implementation, a clerk has some or all of the following information at its disposal to use in choosing a clearinghouse:

• a cached replica set for the parent directory containing the entry of interest

  In this case, the clerk already knows the entire potential set of clearinghouses that might process the request.

• a cached replica set for an ancestor directory

• binding information for clearinghouses that have advertised via the solicitation protocol

  This and the next case allow the clerk to select any available clearinghouse that can provide further guidance. This initiates a process that follows referral pointers through the name space finally to locate the requested entity.

• statically configured binding information for CDS servers.

The algorithm for selecting among multiple possible clearinghouses and CDS servers is not specified. Implementations may follow some rules of probability that reduce the average transactions necessary, balance the load among servers, and account for network topology.

The process of binding and establishing communication with the CDS server that supports a particular clearinghouse is subject to the underlying RPC protocol. This process includes mutual authentication. The clerk generally has several ways of obtaining the appropriate protocol tower for the server. These include:

• finding it in previously cached information

  This information can only be regarded as a hint; the information may be out of date. The address can only be learned with a higher degree of certainty by looking up the clearinghouse object with a confidence level of medium.

• finding it in data returned in the updated ReplicaPointer

• getting it by looking up the clearinghouse object in the name space.

These methods are usually tried in the order listed above, in the interest of securing the best performance.

Referral Handling (Progress Record)

The progress record contains the following flags and other fields:

PR_done

This flag is initially set to FALSE by the clerk and subsequently set to TRUE by the server if the operation was completed successfully. Otherwise, if the returned flag is FALSE, the fully-qualified global name of the request could only partially be resolved; the resolved and residual (unresolved) parts of the fully-qualified global name are returned in the appropriate fields of the progress record.

PR_up

This flag is initially set by the clerk to TRUE, and is never reset by the clerk. As soon as a clearinghouse for an ancestor directory is found, the server sets this flag FALSE to prevent oscillation in the search later on.

The server leaves this flag TRUE if the name points to another cell. The GDA then clears this flag if the foreign cell name is successfully looked up.

PR_linked

This flag is initially set to FALSE by the clerk and then set to TRUE whenever a soft link is followed by the clerk or server in resolving the name.

PR_hitLink

This flag is initially set to FALSE by the clerk and then set to TRUE by a server when it detects a soft link and returns control to the clerk to check for loops in the soft link graph. The clerk resets this flag to FALSE before each new call to a server.

PR_ignoreState

This flag is set to TRUE by the clerk if it wishes the server to ignore the state of a directory/replica and return information regardless.

PR_directory

This flag is set to TRUE by the server whenever the partial or full resolved name is found to be a directory; otherwise (including the case where the full resolved name is NULL) it is set to FALSE.

This flag is required for cache handling when the entry type ET_dirOrObj is requested, because otherwise the clerk does not know which entity (directory or object) was matched if a match is reported.

Timeout

This field is used by servers to compute the minimum timeout for all soft links followed in resolving a name. This information can then be used by the clerk to determine its policy for storing in cache, and may also be returned to the client as an indication of how long the supplied name is valid.

Unresolved Name

This field contains the portion of the original fully-qualified global name that has not yet been located by the servers. The servers are responsible for maintaining this field, and clerks use the value (if any) returned in it as input for subsequent requests for the given operation. The clerk initially sets this field to the requested fully-qualified global name argument of the operation. Generally the field contains one of the following values:

• the entire fully-qualified global name, when the clerk makes its first attempt to get the operation performed

• the entire fully-qualified global name, while the clerk is working up the tree towards the root of the cell

• the portion of the fully-qualified global name that represents the residual of the name (that is, the part that has yet to be resolved)

• the UUID of the last directory resolved

• an entirely new name, after the clerk has traversed a soft link.

Resolved Name

This field contains the portion of the current name which has been successfully processed (resolved) by the servers. The name in this field may be different from the original name supplied by the client if a soft link was traversed. The clerk is not required to do anything with the information in this field, but it may use it for either of the following purposes:

• returning partial information to the client if the operation status is [CDS_UNKNOWNENTRY]

• storing additional information about intermediate names in cache when walking the tree or traversing soft links.

Replica Pointer

This field contains a set of clearinghouses which are believed to have a good probability either of being able to perform the desired operation or of having information about other clearinghouses closer to ones that can actually perform the operation. The clerk initially sets this field to NULL.

Tree Walk Algorithm

The abstract semantic of the tree walk algorithm is as follows:

1. Initialise the progress record and the soft link loop detector.

2. Select the initial clearinghouse.

3. Send request to clearinghouse.

   If the selected clearinghouse is unavailable and the request fails, the clerk selects another clearinghouse that is at its disposal (iterate through previous step). See also Solicitation and Clearinghouse Selection .

4. Loop while PR_done flag of result is FALSE:

   • If a soft link is encountered (that is, the flag PR_hitLink is TRUE), check for loops.

     • If a loop is detected, return to the client with failure status [CDS_POSSIBLECYCLE].

     • If no loop is detected, reinitialise and restart clearinghouse list for resolving new name.

   • Choose a clearinghouse from the list that was returned in Replica Pointer, until the list is exhausted. If there are no more clearinghouses to select from, return to the client with failure status [CDS_NOCOMMUNICATION].

   • Re-request the operation, with updated progress record, from the selected clearinghouse.

5. If PR_done flag is TRUE, return the operation result to the client.

Loop Detection

The algorithm for loop detection and determining the depth of cycles is implementation-specific.

Server Operation

Clearinghouse

The naming of clearinghouses follows a set of rigid rules which ensure that name lookup cannot fail because the clearinghouse in which the directory is storing the object entry cannot be found. In particular, CDS ensures that the following clearinghouse invariant is never violated during normal operation:

• Each clearinghouse contains a replica of the cell root directory.

Clearinghouses are either up or down. When a clearinghouse is up at a given node, that node is acting as a CDS server for that clearinghouse, and may advertise its availability. A server may be controlling more than one clearinghouse simultaneously.

A clearinghouse contains the following types of information:

• operational information:

  • clearinghouse global information

• directories, which contain:

  • directory global information

  • objects, soft links and child pointers.

Information that controls the operation of the clearinghouse as a whole is stored in a pseudo-directory entry in the clearinghouse. The unique identifier (UUID) of this pseudo-directory has the same value as the UUID of the clearinghouse object itself. Thus, clearinghouses can be named and accessed the same way as regular directory entries by clients. The specific attributes applied to these clearinghouse pseudo-directories are defined in Architected Default Attributes .

Every clearinghouse is catalogued in an object entry within the cell root directory. When a server is walking the tree looking for a clearinghouse, it may encounter a clearinghouse object whose information it needs to use for building a referral to the actual clearinghouse. Clearinghouses are accessed by the transaction agents of CDS servers. A set of operational attributes (as determined in Architected Default Attributes ) are exclusively maintained by CDS servers. Any other entries and attributes can be accessed by clerks by means of requests to CDS servers.

Clients can access the clearinghouse operational information by specifying the clearinghouse name with the entry type ET_clearinghouse.

Transaction Agent

The transaction agent processes the following two sets of the transaction protocol:

• the basic clerk/server operations for communicating with clerks

• the directory maintenance operations for synchronising the state of parent and child directories for creation and deletion.

Logically, there is a single transaction agent for each clearinghouse, which processes transactions destined for it. However, the transaction agent has to multiplex the transactions of many clerks simultaneously, and it must thus be able to manage multiple simultaneous execution contexts. Whether this is accomplished by multi-threaded code, multiple processes or other mechanisms is implementation-dependent.

CDS servers export the transaction agent interface with the object UUID of clearinghouses. Clerks bind to clearinghouses using these object UUIDs.

The common operations needed for accessing clearinghouses and processing transactions are described below, in Common Operations of the Transaction Agent . This is followed by a specification of the protocol state model for operations on directory entries. Common Operations of the Transaction Agent , in conjunction with Abstract Definitions of CDS Service Primitives , fully defines the abstract algorithm applied to any other operations.

Common Operations of the Transaction Agent

Each transaction initiated by a clerk consists of a single request. The transaction agent is responsible for processing the request and generating an appropriate response. However, before any request can be processed, the transaction agent must perform the following functions:

1. Determine whether the clearinghouse requested by the clerk is available.

   If the clearinghouse is available, the transaction agent proceeds as described in the following steps. Otherwise, one of the following failure statuses is returned to the clerk:

   [CDS_CLEARINGHOUSEDOWN]

   
   If the clearinghouse is known currently to reside at this transaction agent's server.

   [CDS_UNKNOWNCLEARINGHOUSE]

   
   If the clearinghouse is not known to this transaction agent's server.

2. Find the requested entry in the clearinghouse; if this cannot be done, return the partial result, together with any possible location hints, in an updated progress record to the clerk.

   Since a clearinghouse may contain any part of a path through the name space to the directory which contains the entry of interest, the transaction agent implements a local version of the tree walk algorithm used by clerks. In particular, the transaction agent must perform the following activities:

   1. Determine whether the clearinghouse contains some portion of the path provided by the clerk.

      If it does not, the clearinghouse must either return success with no additional information, or, if the PR_up flag is set to TRUE by the clerk, return a CDS_GDAPointer. If the CDS_GDAPointer does not exist, a [CDS_ROOTLOST] status is returned.

   2. The transaction agent then walks the tree down from the point specified by the clerk in the progress record supplied, until one of the following happens:

      • The entry requested by the clerk is reached.

      • A child pointer entry pointing to a different set of clearinghouses is encountered.

      • A soft link is encountered.

      • An access failure occurs, or a portion of the path is determined not to exist. In this case, the appropriate failure status is returned.

3. Ensure that the client has sufficient permission to access the entry.

   The transaction agent calls the ACL Manager (see Access Control and Protection Model ) to perform the access control verification. If access is denied, the transaction agent returns the appropriate failure status to the clerk and rejects this operation request.

4. After successful verification of access permission on the encountered entry, the transaction agent proceeds as follows, depending on the result in step ii above:

   • If the requested entry is encountered, a handle is generated that can be used to perform the requested operation on the entry, as specified below.

   • If a child pointer entry pointing to a different set of clearinghouses is encountered, the progress record is updated and returned to the clerk.

   • If a soft link is encountered, the target of the soft link is obtained, the progress record is re-initialised with the new name, and control is returned to the clerk after setting the PR_hitLink and PR_linked flags to TRUE.

After obtaining the handle for the target entry of the requested operation, the transaction agent processes the request according to its service definition as follows:

• If the processing is successful, the appropriate information is updated in the clearinghouse and the progress record, status and possibly other output information are updated and returned to the requesting clerk.

  The transaction agent is responsible for creating and updating the appropriate operational attributes associated with entries.

• Unless the requested operation induced a manipulation of directory entries, the transaction affects only a single clearinghouse. Otherwise, the transaction agent may invoke other remote operations on a different clearinghouse before the request can be completed successfully. This specific behaviour is defined below in Transactions for Manipulating Directory Entries .

• If a failure in processing the request is detected, the appropriate failure status is returned to the requesting clerk.

Transactions for Manipulating Directory Entries

The clerk operations that may cause operations of the transaction protocol, which are originated by the initially targeted server and the activities of the transaction agent, are as follows:

cds_CreateDirectory
This operation causes a new directory to be created. It is issued by the clerk to the transaction agent controlling the clearinghouse that is to contain the master replica of the new directory. This may not be the same clearinghouse which holds the master replica for the new directory's parent; hence synchronisation is needed.

The algorithm for creating a new directory is as follows (note that this is an asynchronous series of actions):

1. A new directory is created at the local clearinghouse, and its CDS_ParentPointer attribute is set to point to its (purported) parent directory. Note that it may be true that some directory on the specified path to the new directory may not exist, or that the new directory has a name which conflicts with an already existing child directory. These problems are detected when the attempt is made to create the child pointer entry at the parent's master replica (see the next step).

2. The transaction agent attempts to create the child pointer entry in the parent directory by performing the cds_CreateChild operation. If this fails, the new directory entry is destroyed and the appropriate failure status is returned to the clerk.

3. If the child pointer entry is successfully created, the CDS_ParentPointer attribute is set to the actual name of the parent directory (resolving a possibly linked name).

4. The Access Control List for the directory is appropriately initialised.

cds_DeleteDirectory
This operation removes an existing directory. The directory must be completely empty (that is, no object, soft link or child pointer entries can exist in the directory), or the deletion fails, and the failure status [CDS_NOTEMPTY] is returned to the calling clerk. The operation is issued by the clerk to the transaction agent controlling the master replica of the directory.

The algorithm for deleting a directory proceeds as follows (note that this is an asynchronous series of actions):

1. The transaction agent attempts to delete the child pointer entry in the parent directory by performing the cds_DeleteChild operation. If this fails, the appropriate failure status is returned to the calling clerk.

   Note:

   This operation is performed asynchronously in the background. The directory is marked as dying, and a success status is returned to the clerk. Some time may have elapsed before the child pointer entry is actually deleted and the directory is marked dead.

2. If the child pointer entry is successfully deleted, the local replica of the directory is placed in the dead state for processing the clean-up.

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.