rambocoder edited this page Aug 9, 2012 · 3 revisions

Code naming conventions

Source code files named *_controller.erl implement gen_server OTP behaviour.

Files names *_sup.erl implement supervisor OTP behaviour.

ChicagoBoss boot up sequence

CB uses a rebar plugin to create a command line string that instructs Erlang VM to start an OTP application called boss boss_rebar.erl

When Erlang starts an OTP application, it looks for a file in it's code path, and from the file, the value of {mod, {}} tupple is used to kick off a function call to an Erlang module. {mod, {boss_app, []}} tells Erlang to start the application by calling a function boss_app:start/2 with no _StartArgs because the list of {boss_app, []} tupple is empty. boss_app:start/2 calls boss_sup:start_link() where that function instructs OTP to start a supervisor by executing ?MODULE:init/1 with empty [] arguments.

The result of boss_sup:init/1 are the instructions for OTP supervisor on how to treat the rest of the application.

The most important section in the supervisor configuration is the definition of the worker process that will handle all incoming requests. The worker process is a gen_server defined boss_web_controller.erl

TODO: Describe the restart strategy of boss_web_controller and the children definition

How web request handling works

src/boss_web_controller.erl is responsible for starting web servers and handling all web requests.

During init(Config) function execution, configuration information is loaded from the boss.config file of the directory where ./ or ./ was started, using boss_env:get_env(option_name, default_value) function.

handle_request(Req, RequestMod, ResponseMod) function is executed with Req from the webserver, and the RequestMod and ResponseMod are the server specific atoms for simple_bridge to create simple_bridge request and response wrappers. Simple_bridge wrappers allow to have the same API for handling web server requests and responses without worrying if the web server is Inets, Yaws, Mochiweb, Cowboy or Misultin.

handle_request(Req, RequestMod, ResponseMod) function takes the URL of the request and matches it against the list of base_url tuples of all CB applications in boss.config, if the URL matches the base URL, the function decides if it needs to server static content file or it executes process_request/5 function.

How BossMQ works

CB has a pluggable message que architecture. By default, bmq is used, however any MQ software can be used if the adapter is written to follow the same API as boss_mq_adapter_bmq.erl

boss_web_controller:init/1 starts BossMQ by calling boss_mq:start() and boss_mq module starts boss_mq_sup supervisor that supervises boss_mq worker process, which are gen_servers and their behaviour implementation is in boss_mq_controller.erl

TODO: deep dive into bmq, how mbq and channels supervision trees work.