Initializing Brokers

Brokers (a.k.a. ORB) are the central concept of OiL. They maintain the list of active servants exposed as distributed object that can be invoked remotely. Brokers also create proxies that provide means to perform invocations on remote objects. Basically, brokers can be seen as the way invocation are performed through the distributed environment. Brokers are obtained using operation oil.init.

Start Up

Brokers with multhreading support (flavor contains word cooperative) are able to process incoming requests to registered servants as soon as they are obtained through the oil.init operation.

Shut Down

Method orb:shutdown is used to release all the resources allocated by the broker and terminate its function. Every application shall call this operation to terminate correctly. After a call to this method, no additional invocation is accepted or requested. Any further remote invocation results in errors raised in the requesting process. However, every pending invocation initiated before the call of orb:shutdown are completed normally. This method can be called at any time after the broker is initialized (see oil.init). Operation orb:shutdown should not be called more than once.

Singlethread

Brokers without multithreading support only process incoming requests when the application calls method orb:run. This method executes continuously processing every invocation destined to the servants registered in the broker. The orb:run method only returns when the broker is shutdown.

It is important to notice that with brokers withou multithreading support no invocation will be dispatched to local servants until the method orb:run is called. For instance, suppose we have to register an object into a remote registry represented by a remote object registry that provides method register(user). Moreover, suppose that this register method inspects the object provided as parameter user by calling some methods. In this scenario the following code would result in a deadlock, because during the invocation of registry:register(user) all invocations to user would be help up since orb:run is not executing.

require "oil"

oil.main(function()
  local orb = oil.init()
  
  registry = orb:newproxy(oil.readfrom("registry.ref"))
  registry:register(user) -- never returns because invocations
                          -- to 'user' will never be processed.

  orb:run()
end)

To avoid, this problem, use a combination of methods orb:pending and orb:step. The former indicates whether a remote invocation is pending to be processed or not. The later is used to process a single invocation request. If no invocation request is pending then orb:step blocks until an invocation request is received. The following code is somewhat equivalent to invoke method orb:run:

while orb:pending() do
  orb:step()
end

This model of execution is useful to integrate OiL with other event loops when multithreading is not available. Note however, that while method orb:run is executing, there is not need to call method orb:step.

Copyright (C) 2004-2014 Tecgraf, PUC-Rio