Node.js Domain Module
The Domain module in Node.js simplifies the handling of asynchronous code exceptions and can catch exceptions that cannot be caught by try-catch. The syntax for including the Domain module is as follows:
var domain = require("domain")
The domain module groups multiple different I/O operations. Registering events and callbacks to a domain, when an error event occurs or an error is thrown, the domain object is notified, preserving the context and preventing the program from immediately exiting, unlike process.on('uncaughtException').
The Domain module can be divided into implicit binding and explicit binding:
- Implicit binding: Automatically binds variables defined in the domain context to the domain object.
- Explicit binding: Binds variables not defined in the domain context to the domain object programmatically.
Methods
| No. | Method & Description |
|---|---|
| 1 | domain.run(function) <br> Runs the provided function in the context of the domain, implicitly binding all event emitters, timers, and low-level requests. |
| 2 | domain.add(emitter) <br> Explicitly adds an event emitter. |
| 3 | domain.remove(emitter) <br> Removes an event emitter. |
| 4 | domain.bind(callback) <br> Returns a function that is a wrapper for the provided callback. When this returned function is called, any thrown errors are directed to the domain's error event. |
| 5 | domain.intercept(callback) <br> Similar to domain.bind(callback), except it also intercepts Error objects passed as arguments to the function. |
| 6 | domain.enter() <br> Enters the context of an asynchronous call, binding to the domain. |
| 7 | domain.exit() <br> Exits the current domain, switching to a different chain of asynchronous call contexts. Corresponds to domain.enter(). |
| 8 | domain.dispose() <br> Disposes of a domain object, allowing the Node.js process to reclaim the resources. |
| 9 | domain.create() <br> Returns a new domain object. |
Properties
| No. | Property & Description |
|---|---|
| 1 | domain.members <br> An array of domain timers and event emitters that have been added to the domain object. |
Example
Create a main.js file with the following code:
var EventEmitter = require("events").EventEmitter;
var domain = require("domain");
var emitter1 = new EventEmitter();
// Create a domain
var domain1 = domain.create();
domain1.on('error', function(err){
console.log("domain1 handles this error ("+err.message+")");
});
// Explicit binding
domain1.add(emitter1);
emitter1.on('error',function(err){
console.log("Listener handles this error ("+err.message+")");
});
emitter1.emit('error',new Error('Handled by listener'));
emitter1.removeAllListeners('error');
emitter1.emit('error',new Error('Handled by domain1'));
var domain2 = domain.create();
domain2.on('error', function(err){
console.log("domain2 handles this error ("+err.message+")");
});
// Implicit binding
domain2.run(function(){
var emitter2 = new EventEmitter();
emitter2.emit('error',new Error('Handled by domain2'));
});
domain1.remove(emitter1);
emitter1.emit('error', new Error('Converts to an uncaught exception, system will crash!'));
Executing the above code will result in the following output:
Listener handles this error (Handled by listener)
domain1 handles this error (Handled by domain1)
domain2 handles this error (Handled by domain2)
domain1 handle this error (handled by domain1) domain2 handle this error (handled by domain2)
events.js:72 throw er; // Unhandled 'error' event ^ Error: Conversion to exception, system will crash! at Object.<anonymous> (/www/node/main.js:40:24) at Module._compile (module.js:456:26) at Object.Module._extensions..js (module.js:474:10) at Module.load (module.js:356:32) at Function.Module._load (module.js:312:12) at Function.Module.runMain (module.js:497:10) at startup (node.js:119:16) at node.js:929:3