Publisher objects send messages. More...

Macros
#define	TIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND "com.tibco.ftl.client.publisher.release"
	Ownership of outbound messages; boolean. More...

#define	TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER "com.tibco.ftl.client.publisher.persistence.close.linger"
	Linger duration for persistent publisher close operation; double. More...

#define	TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION "com.tibco.ftl.client.publisher.persistence.retry.duration"
	Retry duration for persistent publisher operations; double. More...

#define	TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT "com.tibco.ftl.client.publisher.max.batch"
	Maximum batch count for non-inline publishers; integer. More...

#define	TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY "com.tibco.ftl.client.publisher.send.policy"
	Publisher send policy; integer. More...

#define	TIB_PUBLISHER_PROPERTY_STRING_LABEL "com.tibco.ftl.client.publisher.label"
	Property name for a publisher label; string. More...

#define	TIB_PUBLISHER_PROPERTY_STRING_REPLY_ENDPOINT "com.tibco.ftl.client.publisher.reply.endpoint"
	Property name for a publisher reply endpoint; string. More...

Typedefs
typedef struct __tibDirectPublisherId *	tibDirectPublisher

typedef struct __tibPublisherId *	tibPublisher
	A publisher object realizes the message-sending functionality of an endpoint within a program. More...

Enumerations
enum	tibPublisher_SendPolicy { TIB_PUBLISHER_SEND_INLINE = 0 , TIB_PUBLISHER_SEND_NON_INLINE = 1 }

Functions
TIB_API void	tibDirectPublisher_Close (tibEx e, tibDirectPublisher publisher)
	Close a direct publisher. More...

TIB_API tibDirectPublisher	tibDirectPublisher_Create (tibEx e, tibRealm realm, const char *endpointName, tibProperties props)
	Create a direct publisher. More...

TIB_API tibint8_t *	tibDirectPublisher_Reserve (tibEx e, tibDirectPublisher publisher, tibint64_t count, tibint64_t totalSize, tibint64_t **sizeArray)
	Reserve a memory buffer for direct publishing. More...

TIB_API void	tibDirectPublisher_SendReserved (tibEx e, tibDirectPublisher publisher)
	Send the data in the reserved buffer. More...

TIB_API void	tibPublisher_Close (tibEx e, tibPublisher publisher)
	Close a publisher. More...

TIB_API tibPublisher	tibPublisher_Create (tibEx e, tibRealm realm, const char *endpointName, tibProperties props)
	Create a publisher. More...

TIB_API void	tibPublisher_Flush (tibEx e, tibPublisher publisher)
	When the publisher's send policy is non-inline, flush all outsanding messages. More...

TIB_API int	tibPublisher_GetMaxBatchCount (tibEx e, tibPublisher pubisher)
	Returns the maximum batch count of a non-inline publisher. More...

TIB_API tibPublisher_SendPolicy	tibPublisher_GetSendPolicy (tibEx e, tibPublisher publisher)
	Returns the send policy of a publisher. More...

TIB_API void	tibPublisher_Send (tibEx e, tibPublisher publisher, tibMessage msg)
	Send a message, one-to-many. More...

TIB_API void	tibPublisher_SendMessages (tibEx e, tibPublisher publisher, tibint32_t msgCount, tibMessage *msgs)
	Send an array of messages, one-to-many. More...

TIB_API void	tibPublisher_SendReply (tibEx e, tibPublisher publisher, tibMessage reply, tibMessage request)
	Send a reply message to a requester. More...

TIB_API tibMessage	tibPublisher_SendRequest (tibEx e, tibPublisher publisher, tibMessage request, tibdouble_t timeout)
	Send a request and wait for reply. More...

TIB_API void	tibPublisher_SendToInbox (tibEx e, tibPublisher publisher, tibInbox inbox, tibMessage msg)
	Send an inbox message. More...

Detailed Description

Publisher objects send messages.

This file defines publisher objects and calls that send messages.

Macro Definition Documentation

◆ TIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

#define TIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND "com.tibco.ftl.client.publisher.release"

Ownership of outbound messages; boolean.

When tibfalse or absent, client program code retains ownership of outbound messages that it sends through this publisher.

When tibtrue, the FTL library accepts ownership of outbound messages that the client sends through this publisher. Client code releases the message object when it invokes the send call; from that moment onward, client code must not reference the message object, because the FTL library can destroy the message object at any time.

Client code can release a message only if client owns the message. In particular, if a subscriber does not release its messages to the callback, then the callback must not send it through a publisher that releases messages. (See TIB_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK .)

See tibPublisher_Create

◆ TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER

#define TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER "com.tibco.ftl.client.publisher.persistence.close.linger"

Linger duration for persistent publisher close operation; double.

When a persistence publisher is configured for non-inline send, and a call to tibPublisher_Close is made while there are still messages waiting to be persisted, the call can be configured to wait for some time before closing the publisher. If the linger period elapses, and the messages have not been successfully persisted, the messages will be discarded. Set this property to control the linger behavior of tibPublisher_Close . The default value is 30 seconds.

Values:

0 Close the publisher immediately.
-1 Close the publisher only after it successfully persisted all outstanding messages
n (Any positive double value) Wait for the publisher to persist outstanding messages for at most n seconds. Proceed with closing the publisher upon success or timeout, whichever comes first.

Closing the realm supersedes and cancels linger behavior.

See tibPublisher_Create

◆ TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

#define TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION "com.tibco.ftl.client.publisher.persistence.retry.duration"

Retry duration for persistent publisher operations; double.

When tibPublisher_Create, tibPublisher_Send, or tibPublisher_SendMessages cannot access the persistence server (usually because of network failure or quorum unavailability), they can automatically retry the interaction. The value of this property overrides the retry behavior of the server. Supply it to the publisher create call.

Values:

0 No retry. The call raises an exception.
-1 Synchronously retry the interaction until it succeeds. The call returns only upon success.
n (Any positive double value) Retry the interaction for n seconds. Return upon success or raise an exception after timeout.

Closing the publisher or the realm supersedes and cancels retry behavior.

See tibPublisher_Create

◆ TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

#define TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT "com.tibco.ftl.client.publisher.max.batch"

Maximum batch count for non-inline publishers; integer.

When a persistence publisher is configured for non-inline send, this is the maximum number of messages that may be in flight to the persistence service at any given time. When this limit is reached, tibPublisher_Send blocks until some messages can be persisted, or a failure occurs. The default value is 100.

The tibPublisher_GetMaxBatchCount call returns the value currently in effect.

See tibPublisher_Create

◆ TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY

#define TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY "com.tibco.ftl.client.publisher.send.policy"

Publisher send policy; integer.

Optimize the publisher for lower latency or greater throughput. The default behavior depends on the realm configuration.

Values:

TIB_PUBLISHER_SEND_INLINE Send the message immediately, to reduce latency.
TIB_PUBLISHER_SEND_NON_INLINE Buffer and batch messages before sending to help improve throughput.

When publishing to a store, and the administrator has configured publisher mode store_confirm_send for the store, the inline send policy causes tibPublisher_Send and tibPublisher_SendMessages to block until the message(s) have been successfully persisted, or until a failure occurs.

When publishing to a store, and the administrator has configured publisher mode store_confirm_send for the store, the non-inline send policy changes the behavior of tibPublisher_Send .

Calls to tibPublisher_Send return immediately, unless the maximum batch count has been reached. The message will be persisted in the background. See TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT .
If a failure occurs in the background, the next call to tibPublisher_Send or tibPublisher_Flush will raise an exception. When this happens the application must assume that the most recent messages, up to the maximum batch count and including the message passed to tibPublisher_Send , have been lost. See TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT .
When the application calls tibPublisher_Close , some messages may not have been persisted. In this case the close call may linger for some time before discarding the messages. See TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER .
Applications may call tibPublisher_Flush to wait for all outstanding messages to be persisted.
If a failure occurs in the background, an advisory will be generated. This is a hint to the application that an error has occurred, and that a call to tibPublisher_Flush will raise an exception. See TIB_ADVISORY_NAME_NONINLINE_SEND_LOSS .

The tibPublisher_GetSendPolicy call returns the value currently in effect.

See tibPublisher_Create

◆ TIB_PUBLISHER_PROPERTY_STRING_LABEL

#define TIB_PUBLISHER_PROPERTY_STRING_LABEL "com.tibco.ftl.client.publisher.label"

Property name for a publisher label; string.

It is good practice to include this property in every publisher create call. Monitoring data incorporates these labels so administrators can identify and distinguish among publishers. Use labels that reveal the unique role and identity of each publisher within the application program.

If a non-inline persistence publisher fails to persist a message, the resulting advisory will include the publisher label. See TIB_ADVISORY_NAME_NONINLINE_SEND_LOSS .

See tibPublisher_Create

◆ TIB_PUBLISHER_PROPERTY_STRING_REPLY_ENDPOINT

#define TIB_PUBLISHER_PROPERTY_STRING_REPLY_ENDPOINT "com.tibco.ftl.client.publisher.reply.endpoint"

Property name for a publisher reply endpoint; string.

For tibPublisher_SendRequest this specifies the endpoint on which the reply is received.

See tibPublisher_Create

Typedef Documentation

◆ tibDirectPublisher

typedef struct __tibDirectPublisherId* tibDirectPublisher

◆ tibPublisher

typedef struct __tibPublisherId* tibPublisher

A publisher object realizes the message-sending functionality of an endpoint within a program.

A publisher object encapsulates all the information that a program needs to send a stream of messages. Publisher objects use the transport and format resources associated with an endpoint (as defined in the realm).

Programs can use a publisher to send messages one-to-many, or one-to-one.

Enumeration Type Documentation

◆ tibPublisher_SendPolicy

enum tibPublisher_SendPolicy

Enumerator
TIB_PUBLISHER_SEND_INLINE	Publish with low latency; integer. If this value is set for property TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY , then publish calls tibPublisher_Send and tibPublisher_SendMessages send messages immediately to reduce latency.
TIB_PUBLISHER_SEND_NON_INLINE	Publish with high throughput; integer. If this value is set for property TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY , then the publish call tibPublisher_Send may batch messages in the background for improved throughput.

Function Documentation

◆ tibDirectPublisher_Close()

TIB_API void tibDirectPublisher_Close	(	tibEx	e,
		tibDirectPublisher	publisher
	)

Close a direct publisher.

Closing a direct publisher invalidates all subsequent method calls, and forces any blocked reserve calls to return.

However, closing a direct publisher does not free its memory. For more information, see "Programming with Direct Publishers" in TIBCO FTL Development.

Parameters

e	The exception object captures information about failures.
publisher	The call closes this direct publisher.

◆ tibDirectPublisher_Create()

TIB_API tibDirectPublisher tibDirectPublisher_Create	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		tibProperties	props
	)

Create a direct publisher.

Applications use direct publisher objects to send data buffers with low latency.

For a complete explanation, including best practices, see "Direct Publishers and Subscribers" in TIBCO FTL Development.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application, endpoints, and transports.
endpointName	The endpoint identifies the publisher's data stream within the realm.
props	Reserved for future use. To ensure forward compatibility, programmers must supply `NULL`.

Returns: On success, this call returns a new direct publisher object.
On failure, this call returns NULL.

◆ tibDirectPublisher_Reserve()

TIB_API tibint8_t * tibDirectPublisher_Reserve	(	tibEx	e,
		tibDirectPublisher	publisher,
		tibint64_t	count,
		tibint64_t	totalSize,
		tibint64_t **	sizeArray
	)

Reserve a memory buffer for direct publishing.

This call reserves two blocks of memory: a data buffer and a size array. The application can fill the memory buffer with one or more data values, and fill the size array with the corresponding sizes (in bytes) of the data values. (In the special case that the application indicates only one data value, this call does not reserve a size array.)

A direct publisher can reserve only one buffer at a time. Subsequent reserve calls in other threads block until the application sends the reserved buffer.

After calling reserve, the application must send the reserved buffer before calling reserve again within the same thread.

To avoid blocking, which increases latency, send the buffer soon after reserving it.

The data buffer and the size array belong to the library.

Parameters

e	The exception object captures information about failures.
publisher	The call reserves memory in this publisher.
count	The application will write this number of data items into the data buffer. The call reserves a size array of this length. Supply a positive integer.
totalSize	The call reserves a data buffer of this size (in bytes).
sizeArray	The call also reserves a size array, and stores the address of that array in this pointer argument. The application will fill the array with the sizes of the data values. If `count` is 1, indicating a single data item, supply `NULL`.

Returns: A pointer to the data buffer.

◆ tibDirectPublisher_SendReserved()

TIB_API void tibDirectPublisher_SendReserved	(	tibEx	e,
		tibDirectPublisher	publisher
	)

Send the data in the reserved buffer.

This call makes the data available to direct subscribers.

After this call returns, the publisher can reserve another buffer.

Parameters

e	The exception object captures information about failures.
publisher	The call sends the reserved buffer of this publisher.

◆ tibPublisher_Close()

TIB_API void tibPublisher_Close	(	tibEx	e,
		tibPublisher	publisher
	)

Close a publisher.

Closing a publisher releases all the resources associated with it (for example, transport resources that are not used in other endpoints).

Parameters

e	The exception object captures information about failures.
publisher	The call closes this publisher.

Returns: void

◆ tibPublisher_Create()

TIB_API tibPublisher tibPublisher_Create	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		tibProperties	props
	)

Create a publisher.

Applications use publisher objects to send messages.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application, endpoints, transports and formats.
endpointName	The endpoint identifies the publisher's data stream within the realm. To use the default endpoint, supply `NULL`.
props	Optional. `NULL` to omit. Persistence properties: TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT Message ownership property: TIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND Other properties: TIB_PUBLISHER_PROPERTY_STRING_LABEL TIB_PUBLISHER_PROPERTY_STRING_REPLY_ENDPOINT TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY

Returns: On success, this call returns a new publisher object.
On failure, this call returns NULL.

◆ tibPublisher_Flush()

TIB_API void tibPublisher_Flush	(	tibEx	e,
		tibPublisher	publisher
	)

When the publisher's send policy is non-inline, flush all outsanding messages.

When a persistence publisher is configured for non-inline send, calls to tibPublisher_Send may return before the message is persisted. Applications may call this function to ensure that all outstanding messages have been persisted (for example, if the application intends to close the publisher). This function blocks until all messages have been persisted, or until a failure occurs. If a failure occurs, this call will raise an exception.

Parameters

e	The exception object captures information about failures.
publisher	The call flushes messages previously sent using this publisher.

Returns: void

◆ tibPublisher_GetMaxBatchCount()

TIB_API int tibPublisher_GetMaxBatchCount	(	tibEx	e,
		tibPublisher	pubisher
	)

Returns the maximum batch count of a non-inline publisher.

Returns the maximum batch count that is in effect for this publisher. Applications may use this call to determine appropriate behavior if a non-inline persistence publisher fails to persist a message.

See TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

Parameters

e	The exception object captures information about failures.
publisher	The publisher.

Returns: The maximum batch count.

◆ tibPublisher_GetSendPolicy()

TIB_API tibPublisher_SendPolicy tibPublisher_GetSendPolicy	(	tibEx	e,
		tibPublisher	publisher
	)

Returns the send policy of a publisher.

Returns the send policy that is in effect for this publisher. Applications may use this call to determine appropriate behavior if a persistence publisher fails to persist a message.

See TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY

Parameters

e	The exception object captures information about failures.
publisher	The publisher.

Returns: The send policy.

◆ tibPublisher_Send()

TIB_API void tibPublisher_Send	(	tibEx	e,
		tibPublisher	publisher,
		tibMessage	msg
	)

Send a message, one-to-many.

If the administrator has configured publisher mode store_confirm_send for the store, a persistence publisher may block in this call until the message has been persisted. Otherwise the call returns immediately, and the message may or may not be stored.

For persistence publishers, the exact semantics depend on the send policy. See TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY .

Parameters

e	The exception object captures information about failures.
publisher	The call sends the message using this publisher.
msg	The call sends this message.

Returns: void

◆ tibPublisher_SendMessages()

TIB_API void tibPublisher_SendMessages	(	tibEx	e,
		tibPublisher	publisher,
		tibint32_t	msgCount,
		tibMessage *	msgs
	)

Send an array of messages, one-to-many.

The application sends each message in the array, in order.

Sending an array of messages eliminates the overhead cost of a separate call for each message.

If the administrator has configured publisher mode store_confirm_send for the store, a persistence publisher will block in this call until all messages have been persisted. Otherwise the call returns immediately, and the messages may or may not be stored.

Parameters

e	The exception object captures information about failures.
publisher	The call sends the messages using this publisher.
msgCount	The number of messages provided in the array.
msgs	The call sends msgCount messages from this array.

Returns: void

◆ tibPublisher_SendReply()

TIB_API void tibPublisher_SendReply	(	tibEx	e,
		tibPublisher	publisher,
		tibMessage	reply,
		tibMessage	request
	)

Send a reply message to a requester.

Upon receiving a request message, send a reply message to the requester.

Parameters

reply	The reply message.
request	The original request message.

◆ tibPublisher_SendRequest()

TIB_API tibMessage tibPublisher_SendRequest	(	tibEx	e,
		tibPublisher	publisher,
		tibMessage	request,
		tibdouble_t	timeout
	)

Send a request and wait for reply.

Send a request and wait for a reply within a specified timeout.

Parameters

request	The request message.
timeout	The maximum time (in seconds) to wait for a reply.

◆ tibPublisher_SendToInbox()

TIB_API void tibPublisher_SendToInbox	(	tibEx	e,
		tibPublisher	publisher,
		tibInbox	inbox,
		tibMessage	msg
	)

Send an inbox message.

Because inbox messages do not trigger the content matchers of other subscribers on the endpoint, they are an efficient way to target a message to a specific destination. For example, you might use an inbox message to query a specific data source, or to reply to a query.

For details about getting an inbox, see tibMessage_GetInbox

Parameters

e	The exception object captures information about failures.
publisher	The call sends the message using this publisher.
inbox	The call sends the message to this inbox.
msg	The call sends this message.

Returns: void

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ TIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

◆ TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER

◆ TIB_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

◆ TIB_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

◆ TIB_PUBLISHER_PROPERTY_INT_SEND_POLICY

◆ TIB_PUBLISHER_PROPERTY_STRING_LABEL

◆ TIB_PUBLISHER_PROPERTY_STRING_REPLY_ENDPOINT

Typedef Documentation

◆ tibDirectPublisher

◆ tibPublisher

Enumeration Type Documentation

◆ tibPublisher_SendPolicy

Function Documentation

◆ tibDirectPublisher_Close()

◆ tibDirectPublisher_Create()

◆ tibDirectPublisher_Reserve()

◆ tibDirectPublisher_SendReserved()

◆ tibPublisher_Close()

◆ tibPublisher_Create()

◆ tibPublisher_Flush()

◆ tibPublisher_GetMaxBatchCount()

◆ tibPublisher_GetSendPolicy()

◆ tibPublisher_Send()

◆ tibPublisher_SendMessages()

◆ tibPublisher_SendReply()

◆ tibPublisher_SendRequest()

◆ tibPublisher_SendToInbox()