|
TIBCO FTL®
|
The group facility can coordinate fault-tolerant operation, or distribute operating roles among application process instances. More...
Macros | |
| #define | TIB_GROUP_ADVISORY_FIELD_GROUP "group" |
| Group name (field name). More... | |
| #define | TIB_GROUP_ADVISORY_FIELD_ORDINAL "ordinal" |
| Group member ordinal (field name). More... | |
| #define | TIB_GROUP_ADVISORY_MODULE_GROUP "GROUP" |
| The advisory message pertains to the group library (module). More... | |
| #define | TIB_GROUP_ADVISORY_NAME_GROUP_STATUS "GROUP_STATUS" |
| The advisory message reports a group status update. More... | |
| #define | TIB_GROUP_ADVISORY_NAME_ORDINAL_UPDATE "ORDINAL_UPDATE" |
| The advisory message reports an ordinal update. More... | |
| #define | TIB_GROUP_FIELD_GROUP_MEMBER_DESCRIPTOR "group_member_descriptor" |
| Group member descriptor (field name). More... | |
| #define | TIB_GROUP_FIELD_GROUP_MEMBER_EVENT "group_member_event" |
| Group member event (field name). More... | |
| #define | TIB_GROUP_FIELD_GROUP_MEMBER_STATUS_LIST "group_member_status_list" |
| Group member status list (field name). More... | |
| #define | TIB_GROUP_FIELD_GROUP_SERVER_AVAILABLE "group_server_available" |
| Group member connection to group server (field name). More... | |
| #define | TIB_GROUP_PROPERTY_BOOLEAN_OBSERVER "com.tibco.ftl.group.observer" |
Property name to monitor a group as an observer; tibbool_t. More... | |
| #define | TIB_GROUP_PROPERTY_DOUBLE_ACTIVATION_INTERVAL "com.tibco.ftl.group.activationinterval" |
Property name for group activation interval; double. More... | |
| #define | TIB_GROUP_PROPERTY_MESSAGE_MEMBER_DESCRIPTOR "com.tibco.ftl.group.memberdescriptor" |
Property name for group member descriptor; tibMessage. More... | |
Typedefs | |
| typedef struct __tibGroupId * | tibGroup |
| A group object represents the membership or potential membership of an application process in a group. More... | |
Enumerations | |
| enum | tibMemberEvent { GROUP_MEMBER_JOINED = 0, GROUP_MEMBER_LEFT, GROUP_MEMBER_DISCONNECTED } |
| Group member event; enumeration. More... | |
| enum | tibMemberServerConnection { GROUP_SERVER_UNAVAILABLE = 0, GROUP_SERVER_AVAILABLE } |
| Group member connection to group server; enumeration. More... | |
Functions | |
| TIBGROUP_API tibint32_t | tibGroup_GetName (tibEx e, tibGroup group, char *buffer, tibint32_t buflen) |
| Get a copy of the group name. More... | |
| TIBGROUP_API tibGroup | tibGroup_Join (tibEx e, tibRealm realm, const char *groupName, tibProperties props) |
| Join a group, and create a group object. More... | |
| TIBGROUP_API void | tibGroup_Leave (tibEx e, tibGroup group) |
| Leave a group, and destroy the group object. More... | |
| TIBGROUP_API const char * | tibGroup_Version (void) |
| Release string identifying the linked TIBCO FTL group library. More... | |
The group facility can coordinate fault-tolerant operation, or distribute operating roles among application process instances.
This file defines the public API of the group facility.
A group server tracks group members, and assigns an ordinal to each member. The group facility raises advisories to inform the member of its current ordinal. Based on its ordinal, each member operates in a particular application-specific role.
The group server also reports the group status as members join and leave the group, or disconnect from the server. The group facility raises advisories to inform members and observers of such changes in status.
| #define TIB_GROUP_ADVISORY_FIELD_GROUP "group" |
Group name (field name).
The string value of the group name field is the name of the group to which the advisory pertains.
| #define TIB_GROUP_ADVISORY_FIELD_ORDINAL "ordinal" |
Group member ordinal (field name).
The positive long value of the ordinal field represents the new ordinal of the group member.
The value -1 indicates that the group object is disconnected from the group server. The group object automatically attempts to reconnect, and continues until the program explicitly destroys it. Meanwhile, the group server could reassign the member's previous ordinal to another group member.
Zero is a reserved value.
| #define TIB_GROUP_ADVISORY_MODULE_GROUP "GROUP" |
The advisory message pertains to the group library (module).
This string value can appear in the module field.
| #define TIB_GROUP_ADVISORY_NAME_GROUP_STATUS "GROUP_STATUS" |
The advisory message reports a group status update.
This string value can appear in the name field.
| #define TIB_GROUP_ADVISORY_NAME_ORDINAL_UPDATE "ORDINAL_UPDATE" |
The advisory message reports an ordinal update.
This string value can appear in the name field.
| #define TIB_GROUP_FIELD_GROUP_MEMBER_DESCRIPTOR "group_member_descriptor" |
Group member descriptor (field name).
This field can can appear in a member status submessage. Its value is a group member descriptor, that is, a message that identifies a group member.
| #define TIB_GROUP_FIELD_GROUP_MEMBER_EVENT "group_member_event" |
Group member event (field name).
This field can appear in a member status submessage. Its value is a tibMemberEvent, that is, a long value that indicates the group member's current state or recent state change.
| #define TIB_GROUP_FIELD_GROUP_MEMBER_STATUS_LIST "group_member_status_list" |
Group member status list (field name).
This field can appear in group status advisory messages. Its value is an array of member status submessages. Each submessage reports the status of one group member.
| #define TIB_GROUP_FIELD_GROUP_SERVER_AVAILABLE "group_server_available" |
Group member connection to group server (field name).
This field can appear in a group status message. Its value is a tibMemberServerConnection, that is, a long value that indicates whether the application process is connected to the group server.
| #define TIB_GROUP_PROPERTY_BOOLEAN_OBSERVER "com.tibco.ftl.group.observer" |
Property name to monitor a group as an observer; tibbool_t.
To monitor a group as an observer, supply this optional property with value tibtrue to tibGroup_Join.
An observer never receives an ordinal, and does not trigger group member events.
| #define TIB_GROUP_PROPERTY_DOUBLE_ACTIVATION_INTERVAL "com.tibco.ftl.group.activationinterval" |
Property name for group activation interval; double.
Supply this (optional) property to tibGroup_Join, which derives heartbeat and timeout intervals from this property value (in seconds). When absent, the default value is 5 seconds.
| #define TIB_GROUP_PROPERTY_MESSAGE_MEMBER_DESCRIPTOR "com.tibco.ftl.group.memberdescriptor" |
Property name for group member descriptor; tibMessage.
To identify a group member to the other members, supply this optional property to tibGroup_Join.
The application programmer determines the content of the descriptor message. In best practice, each group member process supplies a unique descriptor.
| typedef struct __tibGroupId* tibGroup |
A group object represents the membership or potential membership of an application process in a group.
| enum tibMemberEvent |
Group member event; enumeration.
The group member event field of a member status submessage can contain a value of this enumerated type.
Group member connection to group server; enumeration.
The group server available field of a group status advisory message can contain a value of this enumerated type.
| Enumerator | |
|---|---|
| GROUP_SERVER_UNAVAILABLE |
The application is not connected to the group server. |
| GROUP_SERVER_AVAILABLE |
The application is connected to the group server. |
| TIBGROUP_API tibint32_t tibGroup_GetName | ( | tibEx | e, |
| tibGroup | group, | ||
| char * | buffer, | ||
| tibint32_t | buflen | ||
| ) |
Get a copy of the group name.
This call copies the group name string that your program supplied to tibGroup_Join.
If a program passes NULL as the buffer argument, this call returns the length of the group name string, including a NULL terminating character, without actually writing the string.
If the non-NULL buffer is too short for the entire name string, the call writes to the end of the buffer, truncating the string, and returns the actual number of bytes in the buffer.
| e | The exception object captures information about failures. |
| group | The call gets a copy of the name from this group object. |
| buffer | The call copies the name into this string buffer. |
| buflen | The program supplies the length of buffer (in bytes). |
| TIBGROUP_API tibGroup tibGroup_Join | ( | tibEx | e, |
| tibRealm | realm, | ||
| const char * | groupName, | ||
| tibProperties | props | ||
| ) |
Join a group, and create a group object.
The group object connects to the group server.
In best practice, programs first subscribe to the ORDINAL_UPDATE advisory, and then join a group.
| e | The exception object captures information about failures. |
| realm | The call contacts the group server, which operates inside the FTL server for this realm object. Furthermore, the group facility raises advisory messages within this realm. |
| groupName | The program supplies a NULL-terminated string. |
| props | Optional; to omit, supply NULL. Properties configure interaction with the group server and with other group members. |
Leave a group, and destroy the group object.
This call informs the group server that the member is leaving the group. In response, the group server revises the ordinals of the remaining group members appropriately.
This call releases all resources held by the group object.
Before your program calls tibRealm_Close, it must first destroy all the group objects that it has created.
| e | The exception object captures information about failures. |
| group | The call leaves this group. |
| TIBGROUP_API const char* tibGroup_Version | ( | void | ) |
Release string identifying the linked TIBCO FTL group library.
Programs can use this string to output the TIBCO FTL group version in a start banner or in debug output.