|
Size: 4457
Comment:
|
Size: 4734
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 41: | Line 41: |
| enum { MODE_REDUNDANCY, MODE_ROUND_ROBIN, MODE_PREFER_LOCAL } MappingMode; void setMode(const char* name, MappingMode m); |
|
| Line 67: | Line 75: |
| // Get object based on handle void* get(const SAFplus::Handle&) throws(NameException&); |
The Name Service
The Name Service allows users to associate a string with a piece of arbitrary data (often a Handle). Both cluster-wide, node-wide, and process-only data can be associated with the name. This allows name service users to also associate shared memory pointers and local pointers to a particular name. For example, these pointers could reference objects which represent the local instantiation of an entity.
All SAFplus API calls that accept a string name use the Name Service to resolve the string into the actual Handle or object. Since components and services accept a strings in their "create" APIs, it is possible that the end user will never explicitly use the Name Service yet it be heavily utilized.
The name service can also be used independently of other SAFplus APIs by user applications. In this case, its use is a cluster wide name:value dictionary. For example, a handle to the "Active" server application could be stored under a name so that clients can discover which server is active easily.
Implementation
The Name Service is a client library that is linked with every component that uses it. It opens a cluster-wide, shared memory, non-persistent checkpoint using the name service's well-known Handle.
The name service uses this checkpoint to resolve string names into objects.
Header
#include <clNameApi.hxx>
APIs
1 class NameException: public std::exception
2 {
3 ...
4 };
5
6 class NameRegistrar
7 {
8 public:
9
10 /* Associate a name with a handle and pointer and associate a handle with a pointer.
11 If the name does not exist, it is created. If it exists, it is overwritten.
12 If the handle format contains a node or process designator, then this mapping will be removed when the node/process fails.
13
14 the void* object pointer is local to this process; it does not need to be part of the checkpoint.
15
16 This association is valid for all SAFplus API name lookups, and for AMF entity names.
17 */
18 void set(const char* name, SAFplus::Handle handle, void* object=NULL);
19 void set(const std::string& name, SAFplus::Handle handle, void* object=NULL);
20
21 enum {
22 MODE_REDUNDANCY,
23 MODE_ROUND_ROBIN,
24 MODE_PREFER_LOCAL
25 } MappingMode;
26 void setMode(const char* name, MappingMode m);
27
28
29 /* Associate a name with a handle and pointer and associate a handle with a pointer (if object != NULL).
30 If the name does not exist, it is created. If the name exists, this mapping is appended (the original mapping is not removed).
31 If there are multiple associations, the first association will always be returned.
32 If the handle format contains a node or process designator, then this mapping will be removed when the node/process fails.
33 If the name has more than one mapping another mapping will become the default response for this name.
34
35 This association is valid for all SAFplus API name lookups, and for AMF entity names.
36 */
37 void append(const char* name, SAFplus::Handle handle, void* object=NULL);
38 void append(const std::string& name, SAFplus::Handle handle, void* object=NULL);
39
40 // Associate name with arbitrary data. A copy of the data is made.
41 void set(const char* name, const void* data, int length);
42 void set(const std::string& name, const void* data, int length);
43
44 // Associate name with arbitrary data. A copy of the data is NOT made; this call transfers the reference count (ownership) to the callee.
45 void set(const char* name, SAFplus::Buffer*);
46 void set(const std::string& name, SAFplus::Buffer*);
47
48 // Get a handle associated with the data
49 // The SAFplus APIs use these calls to resolve names to handles or objects.
50 std::pair<SAFplus::Handle&,void* object> get(const char* name) throws(NameException&);
51 std::pair<SAFplus::Handle&,void* object> get(const std::string& name) throws(NameException&);
52
53 SAFplus::Handle& get(const char* name) throws(NameException&);
54 SAFplus::Handle& get(const std::string& name) throws(NameException&);
55
56 // Get object based on handle
57 void* get(const SAFplus::Handle&) throws(NameException&);
58
59
60 // Get a handle associated with the data
61 // The SAFplus APIs use these calls to resolve names to handles or objects.
62 // Do not free the returned buffer, call Buffer.decRef();
63 SAFplus::Buffer& get(const char* name) throws(NameException&);
64 SAFplus::Buffer& get(const std::string& name) throws(NameException&);
65
66
67 };
68
69 // Name is a singleton class; only one per process.
70 extern NameRegistrar name;