• Handle

SAFplus::Handle Clusterwide Unique Identifier

The Handle is a Cluster-wide Unique Identifier that can be used to identify something anywhere within the cluster. Objects are identified primarily via handle and only secondarily (through the name service) by string names.

Handle Uses

Well-known constant handles exist that identify certain resources in the system. This solves circular reference issues. For example, the handle service itself uses a checkpoint table to store its handle to object database. But checkpoint tables are identified by handle! So how can the handle service identify its own checkpoint? By a well-known constant handle.

Other handles are dynamically created and associated with an object.

Since handles are cluster wide, they must be able to identify node, process, and memory location. There are different ways to identify these resources and handles come in a variety of different internal formats to reflect this. These formats in turn affect the way handles behave during node and process restarts, and failovers. They also affect how the handle is are resolved. For example, a handle that specifies a process by node/pid will be cleaned up when that process dies. However a handle that specifies a process by SAF component id will only be cleaned up if that component instance is deleted from the AMF database. If the handle sets the "active" bit, that handle will resolve to the active instance of the SAF component. So handles can be used both as a cluster-wide memory pointer, and as a reference to a concept (for example: IP address reject table on the active load balancer) whose specific underlying object can change based on active assignment and failures.

Handle Cleanup

Another feature of clusterwide handles is that they are capable of identifying the node and process where the object they reference exists. This allows an application located on node A to easily clean up handles and associated resources (like context objects) that are being held on behalf of node/process B when node/process B fails.

Special Identifiers

Special identifiers exist that can be constructed from other data (such as the Node's slot number). Other identifiers persist across restarts (well known). Some identifiers do not; they point directly to an object in memory.

Definition

 #include <clHandleApi.hxx>

Internal Details

4 bit identifier type

Identifier Type: Pointer (0)

64 bit pointer 32 bit process id 16 bit node id (slot number and messaging address) 12 bit cluster id 4 bit identifier type

Identifier Type: Transient Well Known (1)

Note, inside handle fields, "0" means NONE, 0xFFFF (all ones of whatever size) means THIS_ENTITY

The meaning of "NONE" might be "all" or "not applicable", depending on the handle. For example, a checkpoint would have a "node" and "process" field of 0 because a checkpoint is the same across all nodes or processes.

"THIS_ENTITY" is NOT a shortcut for the current process or node. If the handle is passed to another process on another node, the handle now refers to the process and node it was sent to. Therefore THIS_ENTITY should be used carefully.

Well Known System Ids

* Node:

* Process:

Handles

A handle is looked up in a Dictionary that is shared by all entities described in the handle. For example, a handle with:

is entry 5 in a Dictionary shared by all nodes and processes in this cluster. But:

is entry 5 in process 2 on node 1 on this cluster

Identifier Type: Persistent Well Known (2)

Same as Well Known (1), except node id and process id are numbers corresponding to SAF names. So must be looked up in a persistent cluster-wide Dictionary.