0ct0pu5
/
tor-router


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848
							<!DOCTYPE html>
<html lang="en">
<head>
    
    <meta charset="utf-8">
    <title>TorPool.js - Documentation</title>
    
    
    <script src="scripts/prettify/prettify.js"></script>
    <script src="scripts/prettify/lang-css.js"></script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>

<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
  <div class="navicon"></div>
</label>

<label for="nav-trigger" class="overlay"></label>

<nav>
    
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="ControlServer.html">ControlServer</a><ul class='methods'><li data-type='method'><a href="ControlServer.html#.instance_info">instance_info</a></li><li data-type='method'><a href="ControlServer.html#close">close</a></li><li data-type='method'><a href="ControlServer.html#createDNSServer">createDNSServer</a></li><li data-type='method'><a href="ControlServer.html#createHTTPServer">createHTTPServer</a></li><li data-type='method'><a href="ControlServer.html#createSOCKSServer">createSOCKSServer</a></li><li data-type='method'><a href="ControlServer.html#createTorPool">createTorPool</a></li><li data-type='method'><a href="ControlServer.html#listen">listen</a></li><li data-type='method'><a href="ControlServer.html#listenTcp">listenTcp</a></li><li data-type='method'><a href="ControlServer.html#listenWs">listenWs</a></li></ul></li><li><a href="DNSServer.html">DNSServer</a><ul class='methods'><li data-type='method'><a href="DNSServer.html#listen">listen</a></li></ul></li><li><a href="HTTPServer.html">HTTPServer</a><ul class='methods'><li data-type='method'><a href="HTTPServer.html#listen">listen</a></li></ul></li><li><a href="SOCKSServer.html">SOCKSServer</a><ul class='methods'><li data-type='method'><a href="SOCKSServer.html#listen">listen</a></li></ul></li><li><a href="TorPool.html">TorPool</a><ul class='methods'><li data-type='method'><a href="TorPool.html#add">add</a></li><li data-type='method'><a href="TorPool.html#add_instance_to_group">add_instance_to_group</a></li><li data-type='method'><a href="TorPool.html#add_instance_to_group_at">add_instance_to_group_at</a></li><li data-type='method'><a href="TorPool.html#add_instance_to_group_by_name">add_instance_to_group_by_name</a></li><li data-type='method'><a href="TorPool.html#create">create</a></li><li data-type='method'><a href="TorPool.html#create_instance">create_instance</a></li><li data-type='method'><a href="TorPool.html#exit">exit</a></li><li data-type='method'><a href="TorPool.html#get_config_at">get_config_at</a></li><li data-type='method'><a href="TorPool.html#get_config_by_name">get_config_by_name</a></li><li data-type='method'><a href="TorPool.html#instance_at">instance_at</a></li><li data-type='method'><a href="TorPool.html#instance_by_name">instance_by_name</a></li><li data-type='method'><a href="TorPool.html#instances_by_group">instances_by_group</a></li><li data-type='method'><a href="TorPool.html#new_identites">new_identites</a></li><li data-type='method'><a href="TorPool.html#new_identites_by_group">new_identites_by_group</a></li><li data-type='method'><a href="TorPool.html#new_identity_at">new_identity_at</a></li><li data-type='method'><a href="TorPool.html#new_identity_by_name">new_identity_by_name</a></li><li data-type='method'><a href="TorPool.html#next">next</a></li><li data-type='method'><a href="TorPool.html#next_by_group">next_by_group</a></li><li data-type='method'><a href="TorPool.html#remove">remove</a></li><li data-type='method'><a href="TorPool.html#remove_at">remove_at</a></li><li data-type='method'><a href="TorPool.html#remove_by_name">remove_by_name</a></li><li data-type='method'><a href="TorPool.html#remove_instance_from_group">remove_instance_from_group</a></li><li data-type='method'><a href="TorPool.html#remove_instance_from_group_at">remove_instance_from_group_at</a></li><li data-type='method'><a href="TorPool.html#remove_instance_from_group_by_name">remove_instance_from_group_by_name</a></li><li data-type='method'><a href="TorPool.html#set_config_all">set_config_all</a></li><li data-type='method'><a href="TorPool.html#set_config_at">set_config_at</a></li><li data-type='method'><a href="TorPool.html#set_config_by_group">set_config_by_group</a></li><li data-type='method'><a href="TorPool.html#set_config_by_name">set_config_by_name</a></li><li data-type='method'><a href="TorPool.html#signal_all">signal_all</a></li><li data-type='method'><a href="TorPool.html#signal_at">signal_at</a></li><li data-type='method'><a href="TorPool.html#signal_by_group">signal_by_group</a></li><li data-type='method'><a href="TorPool.html#signal_by_name">signal_by_name</a></li></ul></li><li><a href="TorProcess.html">TorProcess</a><ul class='methods'><li data-type='method'><a href="TorProcess.html#create">create</a></li><li data-type='method'><a href="TorProcess.html#exit">exit</a></li><li data-type='method'><a href="TorProcess.html#get_config">get_config</a></li><li data-type='method'><a href="TorProcess.html#new_identity">new_identity</a></li><li data-type='method'><a href="TorProcess.html#set_config">set_config</a></li><li data-type='method'><a href="TorProcess.html#signal">signal</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-tor-router.html">tor-router</a></li><li><a href="module-tor-router_ControlServer.html">tor-router/ControlServer</a></li><li><a href="module-tor-router_default_config.html">tor-router/default_config</a></li><li><a href="module-tor-router_default_ports.html">tor-router/default_ports</a></li><li><a href="module-tor-router_DNSServer.html">tor-router/DNSServer</a></li><li><a href="module-tor-router_HTTPServer.html">tor-router/HTTPServer</a></li><li><a href="module-tor-router_launch.html">tor-router/launch</a></li><li><a href="module-tor-router_nconf_load_env.html">tor-router/nconf_load_env</a></li><li><a href="module-tor-router_SOCKSServer.html">tor-router/SOCKSServer</a></li><li><a href="module-tor-router_TorPool.html">tor-router/TorPool</a></li><li><a href="module-tor-router_TorProcess.html">tor-router/TorProcess</a></li><li><a href="module-tor-router_winston_silent_logger.html">tor-router/winston_silent_logger</a></li></ul><h3>Events</h3><ul><li><a href="DNSServer.html#event:instance-connection">instance-connection</a></li><li><a href="HTTPServer.html#event:instance-connection">instance-connection</a></li><li><a href="SOCKSServer.html#event:instance-connection">instance-connection</a></li><li><a href="TorPool.html#event:instance_created">instance_created</a></li><li><a href="TorProcess.html#event:control_listen">control_listen</a></li><li><a href="TorProcess.html#event:controller_ready">controller_ready</a></li><li><a href="TorProcess.html#event:dns_listen">dns_listen</a></li><li><a href="TorProcess.html#event:error">error</a></li><li><a href="TorProcess.html#event:process_exit">process_exit</a></li><li><a href="TorProcess.html#event:ready">ready</a></li><li><a href="TorProcess.html#event:socks_listen">socks_listen</a></li></ul><h3>Global</h3><ul><li><a href="global.html#assembleHost">assembleHost</a></li><li><a href="global.html#cleanUp">cleanUp</a></li><li><a href="global.html#env_whitelist">env_whitelist</a></li><li><a href="global.html#logger">logger</a></li><li><a href="global.html#main">main</a></li><li><a href="global.html#nconf">nconf</a></li><li><a href="global.html#REALM">REALM</a></li><li><a href="global.html#setup_nconf_env">setup_nconf_env</a></li><li><a href="global.html#TOR_ROUTER_PROXY_AGENT">TOR_ROUTER_PROXY_AGENT</a></li></ul>
</nav>

<div id="main">
    
    <h1 class="page-title">TorPool.js</h1>
    

    <section>
        <article>
            <pre class="prettyprint source linenums"><code>/**
 * @author Christoph and Marco Bonelli on Stackoverflow &lt;https://bit.ly/2p6gedO>
 */
Array.prototype.rotate = (function() {
    // save references to array functions to make lookup faster
    var push = Array.prototype.push,
        splice = Array.prototype.splice;

    return function(count) {
        var len = this.length >>> 0, // convert to uint
            count = count >> 0; // convert to int

        // convert count to value in range [0, len)
        count = ((count % len) + len) % len;

        // use splice.call() instead of this.splice() to make function generic
        push.apply(this, splice.call(this, 0, count));
        return this;
    };
})();

const path = require('path');
const fs = require('fs');

const { EventEmitter } = require('eventemitter3');
const Promise = require("bluebird");
const _ = require('lodash');
const WeightedList = require('js-weighted-list');

const TorProcess = require('./TorProcess');

Promise.promisifyAll(fs);

/**
 * Class that represents a pool of Tor processes.
 * @extends EventEmitter
 */
class TorPool extends EventEmitter {
	/**
	 * Creates an instance of `TorPool`.
	 * 
	 * @param {string} tor_path - Path to the Tor executable.
	 * @param {Object|Function} [default_config] -  Default configuration that will be passed to all Tor instances created. Can be a function. See {@link https://bit.ly/2QrmI3o|Tor Documentation} for all possible options
	 * @param {string} data_directory - Parent directory for the data directory of each proccess.
	 * @param {string} load_balance_method - Name of the load balance method to use. See {@link TorPool#load_balance_methods}.
	 * @param {string} [granax_options] - Object containing options that will be passed to granax for each instance.
	 * @param {string} [logger] - A winston logger. If not provided no logging will occur.
	 * 
	 * @throws If "data_directory" is not provided.
	 */
	constructor(tor_path, default_config, data_directory, load_balance_method, granax_options, logger) {
		if (!data_directory)
			throw new Error('Invalid "data_directory"');
		super();
		this._instances = [];
		this._default_tor_config = default_config;
		/**
		 * Parent directory for the data directory of each proccess.
		 * 
		 * @type {string}
		 * @public  
		 */
		this.data_directory = data_directory;
		/**
		 *  Name of the load balance method to use.
		 * 
		 * @type {string}
		 * @public  
		 */
		this.load_balance_method = load_balance_method;
		/**
		 *  Path to the Tor executable.
		 * 
		 * @type {string}
		 * @public  
		 */
		this.tor_path = tor_path;
		/**
		 * The winston logger.
		 * 
		 * @type {Logger}
		 * @public  
		 */
		this.logger = logger || require('./winston_silent_logger');
		/**
		 * Object containing options that will be passed to granax for each instance.
		 * 
		 * @type {Logger}
		 * @public  
		 */
		this.granax_options = granax_options;
	}

	/**
	 * Returns a Set containing the names of all of the groups.
	 * 
	 * @readonly
	 * @type {Set&lt;string>}
	 */
	get group_names() {
		return new Set(_.flatten(this.instances.map((instance) => instance.instance_group).filter(Boolean)));
	}

	/**
	 * Returns an array containing all of the instances in a group.
	 * 
	 * @param {string} group_name - The group to query.
	 * @returns {string[]}
	 * 
	 * @throws If the provided group does not exist
	 */
	instances_by_group(group_name) {
		if (!this.group_names.has(group_name))
			throw new Error(`Group "${group_name}" doesn't exist`);

		let group = this.groups[group_name];
		let arr = [];

		for (let i = 0; i &lt; group.length; i++) {
			arr.push(group[i]);
		}

		return arr;
	}
	
	/**
	 * Adds an instance to a group. If the group doesn't exist it will be created.
	 * 
	 * @param {string} group - The group to add the instance to.
	 * @param {TorProcess} instance - The instance in question.
	 */
	add_instance_to_group(group, instance) {
		instance.definition.Group = _.union(instance.instance_group, [group]);
	}

	/**
	 * Adds an instance to a group by the {@link TorProcess#instance_name} property on the instance. If the group doesn't exist it will be created.
	 * 
	 * @param {string} group - The group to add the instance to.
	 * @param {string} instance_name - The name of the instance in question.
	 * 
	 * @throws If an instance with the name provided does not exist
	 */
	add_instance_to_group_by_name(group, instance_name) {
		let instance = this.instance_by_name(instance_name);

		if (!instance) throw new Error(`Instance "${instance_name}" not found`);

		return this.add_instance_to_group(group, instance);
	}

	/**
	 * Adds an instance to a group by the index of the instance in the pool. If the group doesn't exist it will be created.
	 * 
	 * @param {string} group - The group to add the instance to.
	 * @param {number} instance_index - The index of the instance in question.
	 * 
	 * @throws If an instance with the index provided does not exist.
	 */
	add_instance_to_group_at(group, instance_index) {
		let instance = this.instance_at(instance_index);

		if (!instance) throw new Error(`Instance at "${instance_index}" not found`);

		return this.add_instance_to_group(group, instance);
	}

	/**
	 * Removes an instance from a group.
	 * 
	 * @param {string} group - The group to remove the instance from.
	 * @param {TorProcess} instance - The instance in question.
	 */
	remove_instance_from_group(group, instance) {
		_.remove(instance.definition.Group, (g) => g === group);
	}

	/**
	 * Removes an instance from a group by the {@link TorProcess#instance_name} property on the instance.
	 * 
	 * @param {string} group - The group to remove the instance from.
	 * @param {string} instance_name - The name of the instance in question.
	 * 
	 * @throws If an instance with the name provided does not exist.
	 */
	remove_instance_from_group_by_name(group, instance_name) {
		let instance = this.instance_by_name(instance_name);

		if (!instance) throw new Error(`Instance "${instance_name}" not found`);

		return this.remove_instance_from_group(group, instance);
	}

	/**
	 * Removes an instance from a group by the index of the instance in the pool.
	 * 
	 * @param {string} group - The group to remove the instance from.
	 * @param {number} instance_index - The index of the instance in question.
	 * 
	 * @throws If an instance with the index provided does not exist.
	 */
	remove_instance_from_group_at(group, instance_index) {
		let instance = this.instance_at(instance_index);

		if (!instance) throw new Error(`Instance at "${instance_index}" not found`);

		return this.remove_instance_from_group(group, instance);
	}


	/**
	 * Represents a group of instances. Group is a Proxy with an array as its object. The array is generated by calling {@link TorPool#instances_in_group}.
	 * When called with an index (e.g. `Group[0]`) will return the instance at that index. 
	 * Helper functions are available as properties.
	 * @typedef {TorProcess[]} InstanceGroup
	 * 
	 * @property {Function} add - Adds an instance to the group.
	 * @property {Function} remove - Removes an instance from the group.
	 * @property {Function} add_by_name - Adds an instance to the group by the {@link TorProcess#instance_name} property on the instance.
	 * @property {Function} remove_by_name - Removes an instance from the group by the {@link TorProcess#instance_name} property on the instance.
	 * @property {Function} remove_at - Removes an instance from the group by the index of the instance in the group.
	 * @property {number} length - The size of the group of instances
	 * @property {Function} rotate - Rotates the array of instances  
	 */ 

	 /**
	  * Represents a collection of groups as an associative array. GroupCollection is a Proxy with a Set as its object. The Set is {@link TorPool#group_names}.
	  * If a non-existant group is referenced (e.g. `Groups["doesn't exist"]`) it will be created. So `Groups["doesn't exist"].add(my_instance)` will create the group and add the instance to it.
	  * @typedef {InstanceGroup[]} InstanceGroupCollection
	  */

	/**
	 * Represents all groups currently in the pool.
	 * 
	 * @readonly
	 * @type {InstanceGroupCollection}
	 */
	get groups() {
		let groupHandler = {
			get: (instances, prop) => {
				if (!Number.isNaN(Number(prop)))
					return instances[prop];

				let save_index = () => {
					instances = instances.map((instance, index) => {
						instance._index =  index;
						return instance;
					});
				};

				let { group_name } = instances;
				
				if (prop === 'add') 
					return (instance) => {
						this.add_instance_to_group(group_name, instance);
						save_index();
					};
				
				if (prop === 'add_by_name') {
					return (instance_name) => {
						this.add_instance_to_group_by_name(group_name, instance_name);
						save_index();
					};
				}

				if (prop === 'remove')
					return (instance) => {
						this.remove_instance_from_group(group_name, instance);
						save_index();
					};
			
				if (prop === 'remove_by_name') {
					return (instance_name) => {
						this.remove_instance_from_group_by_name(group_name, instance_name);
						save_index();
					};
				}

				if (prop === 'remove_at') 					
					return (instance_index) => {
						this.remove_instance_from_group(group_name, instances[instance_index]);
						save_index();
					};

				if (prop === 'length')
					return instances.length;

				if (prop === 'rotate') {
					return (num) => {
						instances.rotate(typeof(num) === 'undefined' ? 1 : num);
						save_index();
					};
				}
				
				return void(0);
			}
		};

		let groupsHandler = {
			get: (group_names, prop) => {
				let instances_in_group = [];

				if (group_names.has(prop)) {
					instances_in_group = this.instances.filter((instance) => instance.instance_group.indexOf(prop) !== -1);
				}

				instances_in_group = _.sortBy(instances_in_group, ['_index', 'instance_name']);

				instances_in_group.group_name = prop;

				return new Proxy(instances_in_group, groupHandler);
			}
		};

		return new Proxy(this.group_names, groupsHandler);
	}

	/**
	 * The default configuration that will be passed to each instance. Values from "definition.Config" on each instance will override the default config
	 * 
	 */

	 /** Getter 
	  * 
	  * @type {Object|Function}
	 */
	get default_tor_config() {
		if (typeof(this._default_tor_config) === 'function')
			return this._default_tor_config();
		else if (this._default_tor_config)
			return _.cloneDeep(this._default_tor_config);
		else
			return {};
	}

	/**
	 * Setter
	 * 
	 * @param {Object|Function} value
	 */
	set default_tor_config(value) { this._default_tor_config = value; }

	/**
	 * Returns an enumeration of load balance methods as functions
	 * 
	 * @readonly
	 * @enum {Function}
	 * @static
	 */
	static get load_balance_methods() {
		return Object.freeze({
			round_robin: function (instances) {
				return instances.rotate(1);
			},
			weighted: function (instances) {
				if (!instances._weighted_list) {
					instances._weighted_list = new WeightedList(
						instances.map((instance) => {
							return [ instance.id, instance.definition.Weight, instance ]
						})
					);
				};
				let i = instances._weighted_list.peek(instances.length).map((element) => element.data);
				i._weighted_list = instances._weighted_list;
				return i;
			}
		});
	}

	/**
	 * An array containing all instances in the pool. 
	 * 
	 * @readonly
	 * @type {TorProcess[]}
	 */
	get instances() { 
		return this._instances.slice(0);
	}

	/**
	 * An array containing the names of the instances in the pool.
	 * 
	 * @readonly
	 * @type {string[]}
	 */
	get instance_names() {
		return this.instances.map((i) => i.instance_name);
	}

	/**
	 * Creates an instance then adds it to the pool from the provided definiton. 
	 * Instance will be added (and Promise will resolve) after the instance is fully bootstrapped.
	 * 
	 * @async
	 * @param {InstanceDefinition} [instance_definition={}] - Instance definition that will be used to create the instance.  
	 * @returns {Promise&lt;TorProcess>} - The instance that was created.
	 * 
	 * @throws If an instance with the same {@link InstanceDefinition#Name} already exists.
	 */
	async create_instance(instance_definition) {
		if (!(fs.existsSync(this.data_directory)))
			await fs.mkdirAsync(this.data_directory);

		instance_definition = instance_definition || {};

		if (instance_definition.Name &amp;&amp; this.instance_names.indexOf(instance_definition.Name) !== -1) 
			throw new Error(`Instance named ${instance_definition.Name} already exists`);
		
		this._instances._weighted_list = void(0);
		instance_definition.Config = _.extend(_.cloneDeep(this.default_tor_config), (instance_definition.Config || {}));
		let instance = new TorProcess(this.tor_path, instance_definition, this.granax_options, this.logger);
		instance.definition.Config.DataDirectory = instance.definition.Config.DataDirectory || path.join(this.data_directory, instance.instance_name);
		
		await instance.create();
		
		this._instances.push(instance);

		return await new Promise((resolve, reject) => {
			instance.once('error', reject);

			instance.once('ready', () => {
				/**
				 * Fires when an instance has been created.
				 *
				 * @event TorPool#instance_created
				 * @type {TorProcess}
				 * @param {TorProcess} instance - The instance that was created.
				 */
				this.emit('instance_created', instance);
				resolve(instance);
			});
		});
	}

	/**
	 * Adds one or more instances to the pool from an array of definitions or single definition.
	 * @param {InstanceDefinition[]|InstanceDefinition} instance_definitions
	 * 
	 * @async
	 * @return {Promise&lt;TorProcess[]>}
	 * @throws If `instance_definitions` is falsy.
	 */
	async add(instance_definitions) {
		if (!instance_definitions)
			throw new Error('Invalid "instance_definitions"');
		
		return await Promise.all([].concat(instance_definitions).map((instance_definition) => this.create_instance(instance_definition)));
	}

	/**
	 * Creates one or more instances to the pool from either an array of definitions, a single definition or a number.
	 * If a number is provided it will create n instances with empty definitions (e.g. `TorPool.create(5)` will create 5 instances).
	 * @param {InstanceDefinition[]|InstanceDefinition|number} instance_definitions
	 * 
	 * @async
	 * @return {Promise&lt;TorProcess[]>}
	 * @throws If `instances` is falsy.
	 */
	async create(instances) {
		if (!instances)
			throw new Error('Invalid "instances"');
		
		if (typeof(instances) === 'number') {
			instances = Array.from(Array(instances)).map(() => ({}));
		}
		return await this.add(instances);
	}

	/**
	 * Searches for an instance with the matching {@link TorProcess#instance_name} property.
	 * @param {string} name - Name of the instance to search for
	 * @returns {TorProcess} - Matching instance
	 */
	instance_by_name(name) {
		return this._instances.filter((i) => i.instance_name === name)[0];
	}

	/**
	 * Returns the instance located at the provided index in the pool. 
	 * Is equivalent to `{@link TorPool#instances}[index]`
	 * @param {number} index - Index of the instance in the pool
	 * @returns {TorProcess} - Matching instance
	 */
	instance_at(index) {
		return this._instances[index];
	}

	/**
	 * Removes a number of instances from the pool and kills their Tor processes. 
	 * @param {number} instances - Number of instances to remove
	 * @param {number} [start_at=0] - Index to start removing from
	 * @async
	 * @returns {Promise} - Promise will resolve when the processes are dead
	 */
	async remove(instances, start_at) {
		this._instances._weighted_list = void(0);
		let instances_to_remove = this._instances.splice((start_at || 0), instances);
		await Promise.all(instances_to_remove.map((instance) => instance.exit()));
	}

	/**
	 * Removes an instance at the provided index and kills its Tor process.
	 * @param {number} instance_index - Index of the instance to remove
	 * @async
	 * @returns {Promise} - Promise will resolve when the process is dead
	 */
	async remove_at(instance_index) {
		this._instances._weighted_list = void(0);

		let instance = this._instances.splice(instance_index, 1)[0];
		if (!instance)
			throw new Error(`No instance at "${instance_index}"`);
		
		await instance.exit();
	}

	/**
	 * Removes an instance whose {@link TorProcess#instance_name} property matches the provided name and kills its Tor process.
	 * @param {string} instance_name - Name of the instance to remove
	 * @async
	 * @returns {Promise} - Promise will resolve when the process is dead
	 */
	async remove_by_name(instance_name) {
		let instance = this.instance_by_name(instance_name);
		if (!instance) 
			throw new Error(`Instance "${name}" not found`);
		let instance_index = (this.instances.indexOf(instance));
		await this.remove_at(instance_index);
	}

	/**
	 * Runs the load balance function ({@link TorPool#load_balance_method}) on the array of instances in the pool and returns the first instance in the array.
	 * 
	 * @returns {TorProcess} - The first instance in the modified array.
	 */
	next() {
		this._instances = TorPool.load_balance_methods[this.load_balance_method](this._instances);
		return this.instances[0];
	}

	/**
	 * Rotates the array containing instances in the group provided so that the second element becomes the first element and the first element becomes the last element.
	 * [1,2,3] -> [2,3,1]
	 * @todo Load balance methods other than "round_robin" to be used
	 * @param {string} group - Name of the group
	 * @returns {TorProcess} - The first element in the modified array
	 */
	
	next_by_group(group) {
		this.groups[group].rotate(1);
		return this.groups[group][0];
	}


	/**
	 * Kills the Tor processes of all instances in the pool.
	 * 
	 * @async
	 * @returns {Promise} - Resolves when all instances have been killed.
	 */
	async exit() {
		await Promise.all(this._instances.map((instance) => instance.exit()));
		this._instances = [];
	}

	/**
	 * Gets new identities for all instances in the pool.
	 * 
	 * @async
	 * @returns {Promise} - Resolves when all instances have new identities.
	 */
	async new_identites() {
		await Promise.all(this.instances.map((instance) => instance.new_identity()));
	}

	/**
	 * Gets new identities for all instances in a group.
	 * 
	 * @async
	 * @param {string} - Name of the group.
	 * @returns {Promise} - Resolves when all instances in the group have new identities.
	 */
	async new_identites_by_group(group) {
		await Promise.all(this.instances_by_group(group).map((instance) => instance.new_identity()));
	}

	/**
	 * Gets a new identity for the instance at the provided index in the pool.
	 * 
	 * @async
	 * @param {number} - Index of the instance in the pool.
	 * @returns {Promise} - Resolves when the instance has a new identity.
	 */
	async new_identity_at(index) {
		await this.instances[index].new_identity();
	}

	/**
	 * Gets a new identity for the instance whose {@link TorProcess.instance_name} matches the provided name.
	 * 
	 * @async
	 * @param {string} - Name of the instance.
	 * @returns {Promise} - Resolves when the instance has a new identity.
	 * 
	 * @throws When no instance matched the provided name.
	 */
	async new_identity_by_name(name) {
		let instance = this.instance_by_name(name);
		
		if (!instance) 
			throw new Error(`Instance "${name}" not found`);
		
		await instance.new_identity();
	}

	/**
	 * Get a configuration value from the instance whose {@link TorProcess.instance_name} matches the provided name via the control protocol.
	 * 
	 * @async
	 * @param {string} name - Name of the instance.
	 * @param {string} keyword - Name of the configuration property.
	 * 
	 * @returns {Promise&lt;string[]>} - The configuration property's value.
	 * @throws When no instance matched the provided name.
	 */
	async get_config_by_name(name, keyword) {
		let instance = this.instance_by_name(name);
		if (!instance) 
			throw new Error(`Instance "${name}" not found`);
		
		return await instance.get_config(keyword);
	}

	/**
	 * Set a configuration value for the instance whose {@link TorProcess.instance_name} matches the provided name via the control protocol.
	 * 
	 * @async
	 * @param {string} name - Name of the instance.
	 * @param {string} keyword - Name of the configuration property.
	 * @param {any} value - Value to set the configuration property to.
	 * 
	 * @returns {Promise}
	 * @throws When no instance matched the provided name.
	 */
	async set_config_by_name(name, keyword, value) {
		let instance = this.instance_by_name(name);
		if (!instance) 
			throw new Error(`Instance "${name}" not found`);
		
		return await instance.set_config(keyword, value);
	}

	/**
	 * Get a configuration value from the instance at the index in the pool via the control protocol.
	 * 
	 * @async
	 * @param {number} index - Index of the instance in the pool.
	 * @param {string} keyword - Name of the configuration property.
	 * 
	 * @returns {Promise&lt;string[]>} - The configuration property's value.
	 * @throws When no instance exists at the provided index.
	 */
	async get_config_at(index, keyword) {
		let instance = this.instances[index];
		if (!instance) 
			throw new Error(`Instance at ${index} not found`);
		
		return await instance.get_config(keyword);
	}

	/**
	 * Set a configuration value for the instance at the index in the pool via the control protocol.
	 * 
	 * @async
	 * @param {number} index - Index of the instance in the pool.
	 * @param {string} keyword - Name of the configuration property.
	 * @param {any} value - Value to set the configuration property to.
	 * 
	 * @returns {Promise}
	 * @throws When no instance exists at the provided index.
	 */
	async set_config_at(index, keyword, value) {
		let instance = this.instances[index];
		if (!instance) 
			throw new Error(`Instance at ${index} not found`);
		return await instance.set_config(keyword, value);
	}

	/**
	 * Set a configuration value for all instances in the provided group via the control protocol.
	 * 
	 * @async
	 * @param {string} group - Name of the group.
	 * @param {string} keyword - Name of the configuration property.
	 * @param {any} value - Value to set the configuration property to.
	 * 
	 * @returns {Promise}
	 * @throws When the provided group does not exist.
	 */
	async set_config_by_group(group, keyword, value) {
		return await Promise.all(this.instances_by_group(group).map((instance) => instance.set_config(keyword, value)));
	}

	/**
	 * Set a configuration value for all instances in the pool via the control protocol.
	 * 
	 * @async
	 * @param {string} keyword - Name of the configuration property.
	 * @param {any} value - Value to set the configuration property to.
	 * 
	 * @returns {Promise}
	 */
	async set_config_all(keyword, value) {
		return await Promise.all(this.instances.map((instance) => instance.set_config(keyword, value)));
	}

	/**
	 * Send a signal via the control protocol to all instances in the pool.
	 * 
	 * @async
	 * @param {string} signal - The signal to send.
	 * 
	 * @returns {Promise}
	 */
	async signal_all(signal) {
		await Promise.all(this.instances.map((instance) => instance.signal(signal)));
	}

	/**
	 * Send a signal via the control protocol to an instance whose {@link TorProcess#instance_name} property matches the provided name.
	 * 
	 * @async
	 * @param {string} name - Name of the instance.
	 * @param {string} signal - The signal to send.
	 * 
	 * @returns {Promise}
	 */
	async signal_by_name(name, signal) {
		let instance = this.instance_by_name(name);
		if (!instance) 
			throw new Error(`Instance "${name}" not found`);

		await instance.signal(signal);
	}

	/**
	 * Send a signal via the control protocol to an instance at the provided index in the pool.
	 * 
	 * @async
	 * @param {number} index - Index of the instance in the pool.
	 * @param {string} signal - The signal to send.
	 * 
	 * @returns {Promise}
	 */
	async signal_at(index, signal) {
		let instance = this.instances[index];
		if (!instance) 
			throw new Error(`Instance at ${index} not found`);
		
		await instance.signal(signal);
	}

	/**
	 * Send a signal via the control protocol to all instances in the provided group.
	 * 
	 * @async
	 * @param {string} group - Name of the group.
	 * @param {string} signal - The signal to send.
	 * 
	 * @returns {Promise}
	 * @throws When the provided group does not exist.
	 */
	async signal_by_group(group, signal) {
		await Promise.all(this.instances_by_group(group).map((instance) => instance.signal(signal)));
	}
};

/**
 * Module that contains the {@link TorPool} class.
 * @module tor-router/TorPool
 * @see TorPool
 */
module.exports = TorPool;</code></pre>
        </article>
    </section>


</div>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Sep 25 2018 12:53:23 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>


</body>
</html>