TIBCO FTL®

Macros | Typedefs | Enumerations | Functions
group.h File Reference

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_LIST "group_member_list"
| Group members list (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_LONG_MEMBER_WEIGHT "com.tibco.ftl.group.member.weight"
| Property name group member weight ; `tibuint64_t`. 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 tibMessage | tibGroup_GetMembers (tibEx e, tibGroup id)
| Returns the active members of group. More...
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 tibint64_t | tibGroup_GetOrdinal (tibEx e, tibGroup id)
| Returns the current ordinal for this member of the group. More...
TIBGROUP_API tibint64_t | tibGroup_GetWeight (tibEx e, tibGroup id)
| Returns the weight for this member of the group. 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 void | tibGroup_SetWeight (tibEx e, tibGroup id, tibint64_t weight)
| Set the weight for this member of the group. More...
TIBGROUP_API const char * | tibGroup_Version (void)
| Release string identifying the linked TIBCO FTL group library. More...

## Detailed Description

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.

## Macro Definition Documentation

## ◆ TIB_GROUP_ADVISORY_FIELD_GROUP

#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.

## ◆ TIB_GROUP_ADVISORY_FIELD_ORDINAL

#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.

## ◆ TIB_GROUP_ADVISORY_MODULE_GROUP

#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.

See also
  TIB_ADVISORY_FIELD_MODULE

## ◆ TIB_GROUP_ADVISORY_NAME_GROUP_STATUS

#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.

See also
  TIB_ADVISORY_FIELD_NAME
  TIB_GROUP_ADVISORY_FIELD_GROUP
  TIB_GROUP_FIELD_GROUP_MEMBER_STATUS_LIST
  TIB_GROUP_FIELD_GROUP_MEMBER_DESCRIPTOR
  TIB_GROUP_FIELD_GROUP_MEMBER_EVENT
  TIB_GROUP_FIELD_GROUP_SERVER_AVAILABLE
  TIB_ADVISORY_SEVERITY_INFO

## ◆ TIB_GROUP_ADVISORY_NAME_ORDINAL_UPDATE

#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.

See also
  TIB_ADVISORY_FIELD_NAME
  TIB_GROUP_ADVISORY_FIELD_GROUP
  TIB_GROUP_ADVISORY_FIELD_ORDINAL
  TIB_ADVISORY_SEVERITY_INFO

## ◆ TIB_GROUP_FIELD_GROUP_MEMBER_DESCRIPTOR

#define TIB_GROUP_FIELD_GROUP_MEMBER_DESCRIPTOR "group_member_descriptor"

Group member descriptor (field name).

This field can appear in a member status submessage. Its value is a group member descriptor, that is, a message that identifies a group member.

## ◆ TIB_GROUP_FIELD_GROUP_MEMBER_EVENT

#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.

## ◆ TIB_GROUP_FIELD_GROUP_MEMBER_LIST

#define TIB_GROUP_FIELD_GROUP_MEMBER_LIST "group_member_list"

Group members list (field name).

This field can appear in response message of 'tibGroup_GetMembers' call. Its a message array field where each element is a message containing following field at the most:

See also
  TIB_GROUP_FIELD_GROUP_MEMBER_DESCRIPTOR

## ◆ TIB_GROUP_FIELD_GROUP_MEMBER_STATUS_LIST

#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.

## ◆ TIB_GROUP_FIELD_GROUP_SERVER_AVAILABLE

#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.

## ◆ TIB_GROUP_PROPERTY_BOOLEAN_OBSERVER

#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.

## ◆ TIB_GROUP_PROPERTY_DOUBLE_ACTIVATION_INTERVAL

#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.

## ◆ TIB_GROUP_PROPERTY_LONG_MEMBER_WEIGHT

#define TIB_GROUP_PROPERTY_LONG_MEMBER_WEIGHT "com.tibco.ftl.group.member.weight"

Property name group member weight ; `tibuint64_t`.

To set weight for group member, supply this optional property to tibGroup_Join.

Acceptable values are positive integers.

When absent, the default value is 100. Zero is a special, reserved value for future use.

FTL group service uses relative weight values to determine the ordinal of the group member; members with higher weight take precedence over members with lower weight.

## ◆ TIB_GROUP_PROPERTY_MESSAGE_MEMBER_DESCRIPTOR

#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 Documentation

## ◆ tibGroup

typedef struct __tibGroupId* tibGroup

A group object represents the membership or potential membership of an application process in a group.

## Enumeration Type Documentation

## ◆ tibMemberEvent

enum tibMemberEvent

Group member event; enumeration.

The group member event field of a member status submessage can contain a value of this enumerated type.

See also
  TIB_GROUP_FIELD_GROUP_MEMBER_EVENT

Enumerator
GROUP_MEMBER_JOINED | The member joined the group, or is a member connected to the group server.
GROUP_MEMBER_LEFT | The member left the group using an API call.
GROUP_MEMBER_DISCONNECTED | The member unexpectedly disconnected from the group server.

## ◆ tibMemberServerConnection

enum tibMemberServerConnection

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.

See also
  TIB_GROUP_FIELD_GROUP_SERVER_AVAILABLE

Enumerator
GROUP_SERVER_UNAVAILABLE | The application is not connected to the group server.
GROUP_SERVER_AVAILABLE | The application is connected to the group server.

## Function Documentation

## ◆ tibGroup_GetMembers()

TIBGROUP_API tibMessage tibGroup_GetMembers | ( | tibEx | e,
|  | tibGroup | id
| ) |  |

Returns the active members of group.

This call returns all the members of group that are connected to group server.

Parameters

  e | The exception object captures information about failures.
  id | The call returns the members of this group.

Returns
  Message contains a message array field where each element refers to the active member of this group.

See also
  TIB_GROUP_FIELD_GROUP_MEMBER_LIST

## ◆ tibGroup_GetName()

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.

Parameters

  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).

Returns
  This call returns the length of the group name string, including the NULL terminating character.

See also
  tibGroup_Join

## ◆ tibGroup_GetOrdinal()

TIBGROUP_API tibint64_t tibGroup_GetOrdinal | ( | tibEx | e,
|  | tibGroup | id
| ) |  |

Returns the current ordinal for this member of the group.

This call returns the current ordinal for this member of this group.

Parameters

  e | The exception object captures information about failures.
  id | The call returns the member ordinal of this group.

Returns
  the value of ordinal of this member for the group.

See also
  TIB_GROUP_ADVISORY_FIELD_ORDINAL

## ◆ tibGroup_GetWeight()

TIBGROUP_API tibint64_t tibGroup_GetWeight | ( | tibEx | e,
|  | tibGroup | id
| ) |  |

Returns the weight for this member of the group.

Parameters

  e | The exception object captures information about failures.
  id | The call gets the member weight of this group.

Returns
  This call returns the weight for this member of the group.

See also
  TIB_GROUP_PROPERTY_INT_MEMBER_WEIGHT

## ◆ tibGroup_Join()

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.

Parameters

  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. TIB_GROUP_PROPERTY_DOUBLE_ACTIVATION_INTERVAL TIB_GROUP_PROPERTY_MESSAGE_MEMBER_DESCRIPTOR TIB_GROUP_PROPERTY_BOOLEAN_OBSERVER

Returns
  This call returns a group object.

## ◆ tibGroup_Leave()

TIBGROUP_API void tibGroup_Leave | ( | tibEx | e,
|  | tibGroup | group
| ) |  |

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.

Parameters

  e | The exception object captures information about failures.
  group | The call leaves this group.

Returns
  void

## ◆ tibGroup_SetWeight()

TIBGROUP_API void tibGroup_SetWeight | ( | tibEx | e,
|  | tibGroup | id,
|  | tibint64_t | weight
| ) |  |

Set the weight for this member of the group.

Acceptable values are positive integers. Zero is a special, reserved value for future use.

Programs can adjust their weight at any time to reflect changing conditions. Adjusting weights causes each member to recompute their relative weights of all the members of the group. For large groups this recomputation can affect performance.

Parameters

  e | The exception object captures information about failures.
  id | The call sets the member weight of this group.
  weight | The program supplies the weight of group member.

Returns
  void

See also
  TIB_GROUP_PROPERTY_INT_MEMBER_WEIGHT

## ◆ tibGroup_Version()

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.

Returns
  The release string that identifies the TIBCO FTL group library