Skip to content

Latest commit

 

History

History
140 lines (103 loc) · 5.19 KB

Userguide.md

File metadata and controls

140 lines (103 loc) · 5.19 KB

lbmct v0.5 User Guide - Connected Topics for Ultra Messaging

This page explains how to write Connected Topic application

Publisher Code Outline

See min_ct_src.c for a compilable example.

A publisher of a connected topic needs to perform the following:

Initialization

  • Create a context object with the normal API: lbm_context_create().

  • Create a CT object with the CT API: lbmct_create(). This CT object is associated with a context and should be thought of as analogous to a context. For example, one CT object can host any number of CT Sources (and CT Receivers).

  • Create a CT Source object with a CT API: lbmct_src_create(). Note that the normal source APIs involve allocating a source topic, and then creating the source object. The CT API combines those two operations into a single API. Also, the publisher provides two application callback functions that the CT Source executes as connections are established and closed.

  • Get the underlying UM Source object with the CT API: lbmct_src_get_um_src().

  • Optionally wait for a connection to be created. This is signaled by the CT Source executing the connection creation application callback function.

Steady State

  • Send messages with the normal API: lbm_src_send() (or other normal UM send methods).

Cleanup

  • Delete a CT Source object with a CT API: lbmct_src_delete(). This API will gracefully close any open connections associated with that source.

  • Optionally wait for any open connections to be deleted. This is signaled by the CT Source executing the connection deletion application callback function.

  • Delete the CT object with the CT API: lbmct_delete(). Note that if there are still existing CT Sources (or Receivers), or if CT connections are still in the process of gracefully closing, the call to delete will fail, requiring the application to wait and re-try.

  • Delete the context with the normal API: lbm_context_delete().

Subscriber Code Outline

See min_ct_rcv.c for a compilable example.

A subscriber of a connected topic needs to perform the following:

Initialization

  • Create a context object with the normal API: lbm_context_create().

  • Create a CT object with the CT API: lbmct_create(). This CT object is associated with a context and should be thought of as analogous to a context. For example, one CT object can host any number of CT Receivers (and CT Sources).

  • Create a CT Receiver object with a CT API: lbmct_rcv_create(). Note that the normal receiver APIs involve looking up a receiver topic, and then creating the receiver object. The CT API combines those two operations into a single API. Also, the subscriber provides two application callback functions that the CT Receiver executes as connections are established and closed.

  • As the CT Receiver discovers and connects to CT Sources, it executes the connection creation application callback function.

Steady State

  • As messages are received, the CT Receiver calls the receiver application callback function. The receiver callback is coded and behaves the same as the normal API.

Cleanup

  • Delete a CT Receiver object with a CT API: lbmct_rcv_delete(). This API will gracefully close any open connections associated with that receiver.

  • Optionally wait for any open connections to be deleted. This is signaled by the CT Source executing the connection deletion application callback function.

  • Delete the CT object with the CT API: lbmct_delete(). Note that if there are still existing CT Receivers (or Sources), or if CT connections are still in the process of gracefully closing, the call to delete will fail, requiring the application to wait and re-try.

  • Delete the context with the normal API: lbm_context_delete().

Application Metadata

When a publisher or subscriber create a CT object (with lbmct_create()), the application can optionally pass in a block of binary application metadata. This block of data is delivered to the connected peer in its connection create application callback. This is done symmetrically: publisher metadata is delivered to subscriber, and subscriber metadata is delivered to publisher. Application would normally provide some sort of application-specific identification information so that each application knows "who" the peer is.

No attempt is made to interpret this data. Many applications supply a simple string. If C binary structures are supplied, be aware that the fields will not be marshalled; if platforms of different "endian" are used, it is the application's responsibility to convert between host and network order.