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