The Chicago Boss API is mostly stable, but still might change before 1.0.

BossDB   |   Models   |   Events   |   Web Controllers   |   BossMQ   |   WebSockets   |   Sessions   |   Mail   |   Templates   |   Tests

BossMQ is an abstraction layer for channel-based messaging that can be used to implement real-time notifications (i.e. Comet). With BossMQ, any controller action can function as a long-polling endpoint simply by calling boss_mq:pull/2:

receive_chat('GET', []) ->
   {ok, Timestamp, Messages} = boss_mq:pull("my-channel", now)
   {output, Messages}.

The call to pull/2 blocks until a message arrives on "my-channel". Because of Erlang's lightweight process model, you usually don't need to worry if pull/2 takes a long time to complete.

To send a message to a channel, you call boss_mq:push/2:

boss_mq:push("my-channel", <<"Secret Message">>)

Currently, only an in-memory message queue is supported, so all messaging must occur in the same CB cluster. Additional adapters will be added in the future to support more complex installations.

boss_mq API

pull(Channel::channel()) -> ::mq_return()

Pull messages from the specified Channel. If none are in the queue, blocks until a message is pushed to the queue.

pull(Channel::channel(), Timestampundefined | ::non_neg_integer()) -> ::mq_return()

Pull messages from the specified Channel after Since (a timestamp returned from a previous pull). If no such messages are in the queue, blocks until a message is pushed to the queue.

pull(Channel::channel(), Timestampundefined | ::integer() | {::integer(), ::integer(), ::integer()}, Timeoutinfinity | ::non_neg_integer()) -> ::mq_return()

Pull messages from the specified Channel after Since (a timestamp returned from a previous pull). If no such messages are in the queue, blocks until a message is pushed to the queue, or until Timeout seconds have elapsed.

poll(Channel::channel()) -> ::mq_return()

Like pull/1, but returns immediately if no messages are in the queue.

poll(Channel::channel(), Timestamplast | ::integer()) -> ::mq_return()

Like pull/2, but returns immediately if no matching messages are in the queue.

push(Channel::channel(), Message::term()) -> {ok, ::non_neg_integer()}

Pushes a message to the specified Channel.

now(Channel::channel()) -> ::non_neg_integer()

Retrieves the current time for the server managing Channel.