Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Event Bus

Isaiah Peng edited this page · 4 revisions

EventBus a pub/sub mechanism that allows server side modules to communicate between each other, no matter if they are located in different projects, or different jubilee instance of the same project. It even allows client side JavaScript running in a browser to communicate on the same event bus. It's a huge advantage over the other web servers that you can build real time web application with ease, checkout the chatapp to see how it works.

The event bus forms a distributed peer-to-peer network spanning multiple server nodes and multiple browsers.

The event bus API is incredibly simple. It basically involves registering handlers, unregistering handlers and sending and publishing messages.

Following document are copied from Vert.x site

Registering and Unregistering Handlers

To set a message handler on the address test.address, you call the method register_handler on the EventBus class

id = Vertx::EventBus.register_handler('test.address') do |message|
    puts "Got message body #{message.body}" 
end

It's as simple as that. The handler will then receive any messages sent to that address. The object passed into the handler is an instance of class Message. The body of the message is available via the body attribute.

The return value of register_handler is a unique handler id which can used later to unregister the handler.

When you register a handler on an address and you're in a cluster it can take some time for the knowledge of that new handler to be propagated across the entire cluster. If you want to be notified when that has completed you can optionally specify a block to the register_handler method as the third argument. This block will then be called once the information has reached all nodes of the cluster. E.g. :

Vertx::EventBus.register_handler('test.address', myHandler) do
    puts 'Yippee! The handler info has been propagated across the cluster'
end

To unregister a handler it's just as straightforward. You simply call unregister_handler passing in the id of the handler:

Vertx::EventBus.unregister_handler('test.address', id)

As with registering, when you unregister a handler and you're in a cluster it can also take some time for the knowledge of that unregistration to be propagated across the entire to cluster. If you want to be notified when that has completed you can optionally specify another block to the unregister_handler method:

Vertx::EventBus.unregister_handler(id) do
    puts 'Yippee! The handler unregister has been propagated across the cluster'
end

If you want your handler to live for the full lifetime of your verticle there is no need to unregister it explicitly - vert.x will automatically unregister any handlers when the verticle is stopped.

Publishing messages

Publishing a message is also trivially easy. Just publish it specifying the address, for example:

Vertx::EventBus.publish("test.address", 'hello world')

That message will then be delivered to all handlers registered against the address "test.address".

Sending messages

Sending a message will result in only one handler registered at the address receiving the message. This is the point to point messaging pattern. The handler is chosen in a non strict round-robin fashion.

Vertx::EventBus.send("test.address", 'hello world')

Replying to messages

Sometimes after you send a message you want to receive a reply from the recipient. This is known as the request-response pattern.

To do this you send a message, and specify a block as a reply handler. When the receiver receives the message there is a method reply on the Message instance that is passed into the handler.

When this method is invoked it causes a reply to be sent back to the sender where the reply handler is invoked. An example will make this clear:

The receiver:

Vertx::EventBus.register_handler('test.address') do |message|
  puts "I received a message #{message.body}"

  # Do some stuff...
  # Now reply to it

  message.reply('This is a reply')
end

The sender:

Vertx::EventBus.send('test.address', 'This is a message') do |message|
  puts "I received a reply #{message.body}"
end

It is legal also to send an empty reply or null reply.

The replies themselves can also be replied to so you can create a dialog between two different verticles consisting of multiple rounds.

Message types

The message you send can be any of the following types:

FixNum
Float
String
Boolean
Hash - this will be treated as a JSON object
Vert.x Buffer

Vert.x buffers and Hashes are copied before delivery if they are delivered in the same JVM, so different verticles can't access the exact same object instance.

Here are some more examples:

Send some numbers:

Vertx::EventBus.send('test.address', 1234)
Vertx::EventBus.send('test.address', 3.14159)

Send a boolean:

Vertx::EventBus.send('test.address', true)

Send a JSON object:

myObj = {
  'name' => 'Tim',
  'address' => 'The Moon',
  'age' => 457
}
Vertx::EventBus.send('test.address', myObj)

nil messages can also be sent:

Vertx::EventBus.send('test.address', nil)

It's a good convention to have your verticles communicating using JSON - this is because JSON is easy to generate and parse for all the languages that Vert.x supports.

Distributed event bus

To make each Vert.x instance on your network participate on the same event bus, start each Vert.x instance with the --cluster command line switch.

See the cluster page for more information on this.

Once you've done that, any Vert.x instances started in cluster mode will merge to form a distributed event bus.

For more details, checkout the vertx document about event bus.

Something went wrong with that request. Please try again.