TIBCO FTL®
|
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_RETRY_DURATION "com.tibco.ftl.client.publisher.persistence.retry.duration" |
Retry duration for persistent publisher operations; double. More... | |
#define | TIB_PUBLISHER_PROPERTY_STRING_LABEL "com.tibco.ftl.client.publisher.label" |
Property name for a publisher label; 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... | |
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_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_SendToInbox (tibEx e, tibPublisher publisher, tibInbox inbox, tibMessage msg) |
Send an inbox message. More... | |
Publisher objects send messages.
This file defines publisher objects and calls that send messages.
#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 .)
#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:
Closing the publisher or the realm supersedes and cancels retry behavior.
#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.
The library does not use labels internally.
typedef struct __tibDirectPublisherId* tibDirectPublisher |
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.
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.
e | The exception object captures information about failures. |
publisher | The call closes this direct publisher. |
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.
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 . |
NULL
. 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.
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. |
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.
e | The exception object captures information about failures. |
publisher | The call sends the reserved buffer of this publisher. |
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).
e | The exception object captures information about failures. |
publisher | The call closes this publisher. |
TIB_API tibPublisher tibPublisher_Create | ( | tibEx | e, |
tibRealm | realm, | ||
const char * | endpointName, | ||
tibProperties | props | ||
) |
Create a publisher.
Applications use publisher objects to send messages.
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: Message ownership property: Other properties: |
NULL
. TIB_API void tibPublisher_Send | ( | tibEx | e, |
tibPublisher | publisher, | ||
tibMessage | msg | ||
) |
Send a message, one-to-many.
e | The exception object captures information about failures. |
publisher | The call sends the message using this publisher. |
msg | The call sends this message. |
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.
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. |
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
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. |