Chicago Boss home

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::string()) -> {ok, Timestamp, [Message]} | {error, Reason}

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

pull(Channel::string(), Since::integer() | last | now) -> {ok, Timestamp, [Message]} | {error, Reason}

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::string(), Since::integer() | last | now, Timeout::integer()) -> {ok, Timestamp, [Message]} | {error, Reason}

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::string()) -> {ok, Timestamp, [Message]} | {error, Reason}

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

poll(Channel::string(), Since::integer() | last) -> {ok, Timestamp, [Message]} | {error, Reason}

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

push(Channel::string(), Message) -> {ok, Timestamp}

Pushes a message to the specified Channel.

now(Channel::string()) -> Timestamp

Retrieves the current time for the server managing Channel.