package.json

{
  "name": "partner",
  "version": "0.6.1",
  "description": "Child process management. Support to create, manage, interact between child process.",
  "email": "tangkhaiphuong@gmail.com",
  "author": {
    "name": "Tang Khai Phuong"
  },
  "main": "./lib/partner",
  "scripts": {
    "test": "node_modules/.bin/intern-client config=test/intern-config"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/tangkhaiphuong/partner.git"
  },
  "bugs": {
    "url": "https://github.com/tangkhaiphuong/partner/issues"
  },
  "keywords": [
    "process",
    "parallel",
    "distribution"
  ],
  "license": "MIT",
  "maintainers": [
    {
      "name": "tangkhaiphuong",
      "email": "tangkhaiphuong@gmail.com"
    }
  ],
  "homepage": "https://github.com/tangkhaiphuong/partner",
  "readme": "# partner \r\n\r\nWrapping `require(\"child_process\")` module. Supporting to manage child process status such as start, \r\nstop. Handle message, exit status, request/response between parent and child.\r\n\r\nInstallation\r\n----\r\n    npm install partner\r\nUsage\r\n====\r\n`var partner = require(\"partner\");`\r\n\r\n### partner.on(\"start\", function(data, master, done){ })\r\n\r\nHandling start event.\r\n\r\n`start` start event.\r\n\r\n`function(data, master, done)` callback function.\r\n\r\n* `data` Start argument.\r\n* `master` false it is child process otherwise callback is invoked from `partner.start([data], [function(error){ }])`\r\n* `done(error)` callback notify to master.\r\n\r\n### partner.on(\"stop\", function(data, master, done)){ })\r\n\r\nHandling stop event.\r\n\r\n`stop` stop event.\r\n\r\n`function(data, master, done)` callback function.\r\n\r\n* `data` Stop argument.\r\n* `master` false it is child process otherwise callback is invoked from `partner.stop([data], [function(error){ }])`\r\n* `done(error)` callback notify to master.\r\n\r\n### partner.on(\"message\", function(message, data, master){ })\r\n\r\nHandling message.\r\n\r\n`message` message event.\r\n\r\n`function(message, data, master)` callback function.\r\n\r\n* `message` Message name.\r\n* `data` Data payload\r\n* `master` false it is child process otherwise callback is invoked from `partner.send(message, data, [sendHandle])`\r\n\r\n### partner.handle(`function(message, data, response){ }`)\r\n\r\nHandling request from parent\r\n\r\n`function(message, data, response)` callback function.\r\n\r\n* `message` Message name.\r\n* `data` Data payload\r\n* `response` Callback function(error, data). Invoke to send response to parent.\r\n\r\n### partner.request(message, data, `function(error, data, message){ }`)\r\n\r\nRequest parent handle.\r\n\r\n* `message` Message name.\r\n* `data` Data payload\r\n* `function(error, data, message)` callback function.\r\n\r\n### partner.with(`modulePath|alias`, [strategy])\r\n\r\nAsking parent dispatches request/message from other children by module path or alias.\r\n\r\n* `module|alias` Module file path or alias to handle request.\r\n* `strategy` Strategy for select partner to handle. There are: \"first\", \"last\", \"next\", \"random\", index-number\r\n\r\n`var friend = partner.with(\"modulePath\", [strategy])`\r\n\r\n* `friend.request(message, data, function(error, data, message)){ }`) Request handle\r\n* `friend.send(message, data, [sendHandle])` Send message.\r\n* `friend.register(function(message, data) { ... })` Register handle message.\r\n* `friend.unRegister(function(message, data) { ... })` Unregister handle message.\r\n\r\n### partner.select(`modulePath|alias`, [strategy]);\r\n\r\nSelect a child by file path or alias and request handle with strategy.\r\n\r\n* `module|alias` Module file path or alias to handle request.\r\n* `strategy` Strategy for select partner to handle. There are: \"first\", \"last\", \"next\", \"random\", index-number\r\n\r\n`var child = partner.select(\"modulePath\", [strategy])`\r\n\r\n* `child.request(message, data, function(error, data, message)){ }`) Request handle\r\n* `child.send(message, data, [sendHandle])` Send message.\r\n\r\n### partner.send(message, data, [sendHandle])\r\n\r\nSending message. If itself is child process then send back to parent, otherwise raise \"message\" event for itself.\r\n\r\n* `message` Message in string format.\r\n* `data` Data payload.\r\n\r\n### partner.broadcast(message, data, [sendHandle])\r\n\r\nSending message for all children process.\r\n\r\n* `message` Message in string format.\r\n* `data` Data payload.\r\n\r\n### partner.stop([data], [function(error){}])\r\n\r\nSending current process. If itself is child process then do nothing, otherwise raise \"stop\" event for itself.\r\n\r\n* `data` Optional data payload.\r\n* `function(error)` callback function.\r\n\r\n### partner.start([data], [function(error){}])\r\n\r\nStart current process. If itself is child process then do nothing, otherwise raise \"start\" event for itself.\r\n\r\n* `data` Optional data payload.\r\n* `function(error)` callback function.\r\n\r\n### partner.list(): Array\r\n\r\nList all children process.\r\n\r\n### partner.create(`modulePath`, [alias]): object\r\n\r\nCreate child process with JavaScript file path, alias. Return new partner object with methods:\r\n\r\n`var child = partner.create(\"file://./child.js\");`\r\n\r\n* `child.setOptions(options)` set options for child process like: `child_process.fork(modulePath, [args], [options])`.\r\n\r\n* `child.getOptions()` get options.\r\n\r\n* `child.setArguments(args)` set arguments for child process like: `child_process.fork(modulePath, [args], [options])`.\r\n\r\n* `child.getArguments()` get arguments.\r\n\r\n* `child.getFile()` get absolute file path.\r\n\r\n* `child.get()` get ChildProcess object.\r\n\r\n* `child.start([data], [callback])` start child process with argument data. Callback if partner invoke done([error], \r\n[data])\r\n\r\n* `child.stop([data], [callback])`  stop child process with argument data. Callback if partner invoke done([error], [data])\r\n\r\n* `child.send(message, data, [sendHandle])` send message to child process with data and sendHandler\r\n\r\n* `child.request(message, data, function(error, data, message){ })` request child process message and waiting for\r\nresponse in callback.\r\n\r\n* `child.broadcast(message, data, [sendHandle])` send message to all children process except itself with data and \r\nsendHandler.\r\n\r\n* `child.exit()` force child process must stop.\r\n\r\n* `child.on(\"message\", function(message, data){} )` handle message event is sent back from child.\r\n\r\n* `child.on(\"exit\", function(errors, data){} )` handle exit event if child is kill or die. Data is start data.\r\n\r\n* `child.handle(function(message, data, response){ })` handle request from child.\r\n\r\n# Examples\r\n\r\n<pre><code>\r\nvar partner, child;\r\npartner = require(\"../../lib/partner\");\r\nchild = partner.create(\"file://\" + __filename);\r\n/* Handle child message. */\r\nchild.on(\"message\", function(message, data){\r\n  /* Go message from child. */\r\n  console.log(\"------------------------------\");\r\n  return console.log(\"[Child::Message]: Got message from child: \" + JSON.stringify({\r\n    message: message,\r\n    data: data\r\n  }));\r\n});\r\n/* Handle child exit. */\r\nchild.on(\"exit\", function(errors, data){\r\n  /* Go message from child. */\r\n  console.log(\"[Child::Exit]: Child is killed. Start again with arguments: \" + JSON.stringify(data));\r\n  /* Start again. */\r\n  this.start(data);\r\n  return console.log(\"------------------------------\");\r\n});\r\n/* Handle child request. */\r\nchild.handle(function(message, data, response){\r\n  /* Go request from child. */\r\n  console.log(\"[Master::Request]: Got request from child: \" + JSON.stringify({\r\n    message: message,\r\n    data: data\r\n  }));\r\n  switch (message) {\r\n  case \"Multiply\":\r\n    return response(null, data.first * data.second);\r\n  default:\r\n    return response(\"Master don't handle it!\");\r\n  }\r\n});\r\n/* Handle start event. */\r\npartner.on(\"start\", function(data, master){\r\n  if (master) {\r\n    console.log(\"[Start]: I'm master: \" + JSON.stringify(data));\r\n    /* Start child if itself is master. */\r\n    child.start(\"Child::Start\", function(error){\r\n      console.log(\"[Start]: Got error: \", error);\r\n      process.exit();\r\n    });\r\n    /* Send message to child. */\r\n    child.send(\"Hello\", \"How are you?\");\r\n    console.log(\"------------------------------\");\r\n    /* Request message to child process. */\r\n    child.request(\"Sum\", {\r\n      first: 1,\r\n      second: 2\r\n    }, function(error, data, message){\r\n      console.log(\"------------------------------\");\r\n      if (error != null) {\r\n        return console.error(\"[\" + message + \"::Master::Response]: Got error: \", error);\r\n      }\r\n      return console.log(\"[\" + message + \"::Master::Response]: \" + JSON.stringify({\r\n        message: message,\r\n        data: data\r\n      }));\r\n    });\r\n    /* Request message to child process with no handle. */\r\n    child.request(\"NoHandler\", \"Data\", function(error, data, message){\r\n      console.log(\"------------------------------\");\r\n      if (error != null) {\r\n        return console.error(\"[\" + message + \"::Master::Response]: Got error: \", error);\r\n      }\r\n      return console.log(\"[\" + message + \"::Master::Response]: \" + JSON.stringify({\r\n        message: message,\r\n        data: data\r\n      }));\r\n    });\r\n    /* Stop entry point after 6 second. */\r\n    setTimeout(function(){\r\n      console.log(\"------------------------------\");\r\n      return partner.stop(\"Master::Stop\");\r\n    }, 3000);\r\n    /* Kill child after 2 second. */\r\n    return setTimeout(function(){\r\n      console.log(\"------------------------------\");\r\n      console.log(\"            child.get().kill()\");\r\n      return child.get().kill();\r\n    }, 2000);\r\n  } else {\r\n    console.log(\"[Start]: I'm child: \" + JSON.stringify(data));\r\n    console.log(\"------------------------------\");\r\n    partner.send(\"???\", \"Who am I?\");\r\n    /* Ask master request. */\r\n    partner.request(\"Multiply\", {\r\n      first: 10,\r\n      second: 10\r\n    }, function(error, data, message){\r\n      console.log(\"------------------------------\");\r\n      if (error != null) {\r\n        return console.error(\"[\" + message + \"::Child::Response]: Got error: \", error);\r\n      }\r\n      return console.log(\"[\" + message + \"::Child::Response]: \" + JSON.stringify({\r\n        message: message,\r\n        data: data\r\n      }));\r\n    });\r\n    /* Request message to child process with no handle. */\r\n    return partner.request(\"Reject\", \"Data\", function(error, data, message){\r\n      console.log(\"------------------------------\");\r\n      if (error != null) {\r\n        return console.error(\"[\" + message + \"::Child::Response]: Got error: \", error);\r\n      }\r\n      return console.log(\"[\" + message + \"::Child::Response]: \" + JSON.stringify({\r\n        message: message,\r\n        data: data\r\n      }));\r\n    });\r\n  }\r\n});\r\n/* Handle stop event. */\r\npartner.on(\"stop\", function(data, master){\r\n  if (master) {\r\n    /* Stop child if itself is master. */\r\n    child.stop(\"Child::Stop\");\r\n    console.log(\"[Stop]: I'm master: \" + JSON.stringify(data));\r\n    /* Stop child after 1 second. */\r\n    setTimeout(function(){\r\n      console.log(\"------------------------------\");\r\n      console.log(\"            child.stop('Child::Stop')\");\r\n      return child.stop(\"Child::Stop\");\r\n    }, 2000);\r\n    /* Force kill child after 3 second. */\r\n    return setTimeout(function(){\r\n      console.log(\"------------------------------\");\r\n      console.log(\"            child.exit()\");\r\n      return child.exit();\r\n    }, 3000);\r\n  } else {\r\n    return console.log(\"[Stop]: I'm child: \" + JSON.stringify(data));\r\n  }\r\n});\r\n/* Handle message event. */\r\npartner.on('message', function(message, data, master){\r\n  if (master) {\r\n    return console.log(\"[Message]: Got message from itself: \" + JSON.stringify({\r\n      message: message,\r\n      data: data\r\n    }));\r\n  } else {\r\n    return console.log(\"[Message]: Got message from parent: \" + JSON.stringify({\r\n      message: message,\r\n      data: data\r\n    }));\r\n  }\r\n});\r\n/* Handle default request */\r\npartner.handle(function(message, data, response){\r\n  /* Go request from child. */\r\n  console.log(\"[Child::Request]: Got request from parent: \" + JSON.stringify({\r\n    message: message,\r\n    data: data\r\n  }));\r\n  switch (message) {\r\n  case \"Sum\":\r\n    return response(null, data.first + data.second);\r\n  default:\r\n    return response(\"I don't handle it!\");\r\n  }\r\n});\r\n/* Start entry point. */\r\npartner.start(\"Master::Start\");\r\n\r\n</code></pre>\r\n\r\n# TODO\r\n* Support socket.io to connect other process cross network.\r\n\r\n# License\r\n\r\nMIT\r\n"
}