time-to-botec

factory.js (8799B)

---

 /**
 * @license Apache-2.0
 *
 * Copyright (c) 2018 The Stdlib Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
 'use strict';
 
 // MODULES //
 
 var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
 var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive;
 var isCollection = require( '@stdlib/assert/is-collection' );
 var isTypedArrayLike = require( '@stdlib/assert/is-typed-array-like' );
 var isArrayBuffer = require( '@stdlib/assert/is-arraybuffer' );
 var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
 var setReadOnlyAccessor = require( '@stdlib/utils/define-nonenumerable-read-only-accessor' );
 var ctors = require( './../../typed-ctors' );
 var copy = require( '@stdlib/utils/copy' );
 var ArrayBuffer = require( './../../buffer' );
 var ceil = require( '@stdlib/math/base/special/ceil' );
 var floor = require( '@stdlib/math/base/special/floor' );
 var ceil2 = require( '@stdlib/math/base/special/ceil2' );
 var log2 = require( '@stdlib/math/base/special/log2' );
 var min = require( '@stdlib/math/base/special/min' );
 var defaults = require( './defaults.json' );
 var validate = require( './validate.js' );
 var createPool = require( './pool.js' );
 var BYTES_PER_ELEMENT = require( './bytes_per_element.json' );
 
 
 // MAIN //
 
 /**
 * Creates a typed array pool.
 *
 * @param {Options} [options] - pool options
 * @param {NonNegativeInteger} [options.highWaterMark] - maximum total memory which can be allocated
 * @throws {TypeError} options argument must be an object
 * @throws {TypeError} must provide valid options
 * @returns {Function} allocator
 *
 * @example
 * var typedarraypool = factory();
 *
 * // Allocate an array of doubles:
 * var arr = typedarraypool( 5, 'float64' );
 * // returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 0.0 ]
 *
 * arr[ 0 ] = 3.14;
 * arr[ 1 ] = 3.14;
 *
 * // ...
 *
 * // Free the allocated memory to be used in a future allocation:
 * typedarraypool.free( arr );
 */
 function factory( options ) {
 	var nbytes;
 	var pool;
 	var opts;
 	var err;
 
 	opts = copy( defaults );
 	if ( arguments.length ) {
 		err = validate( opts, options );
 		if ( err ) {
 			throw err;
 		}
 	}
 	pool = createPool( ceil( log2( opts.highWaterMark ) ) );
 	nbytes = 0;
 
 	setReadOnly( malloc, 'malloc', malloc ); // circular reference
 	setReadOnly( malloc, 'calloc', calloc );
 	setReadOnly( malloc, 'free', free );
 	setReadOnly( malloc, 'clear', clear );
 	setReadOnly( malloc, 'highWaterMark', opts.highWaterMark );
 	setReadOnlyAccessor( malloc, 'nbytes', getBytes );
 
 	return malloc;
 
 	/**
 	* Returns the number of allocated bytes.
 	*
 	* @private
 	* @returns {NonNegativeInteger} number of allocated bytes
 	*/
 	function getBytes() {
 		return nbytes;
 	}
 
 	/**
 	* Returns an array buffer.
 	*
 	* @private
 	* @param {NonNegativeInteger} n - number of bytes
 	* @returns {(ArrayBuffer|null)} array buffer or null
 	*/
 	function arraybuffer( n ) {
 		var buf;
 		var i;
 
 		// Convert the number of bytes to an index in our pool table:
 		i = log2( n );
 
 		// If we already have an available array buffer, use it...
 		if ( i < pool.length && pool[ i ].length ) {
 			return pool[ i ].pop();
 		}
 		// Before allocating a new array buffer, ensure that we have not exceeded the maximum number of bytes we are allowed to allocate...
 		if ( nbytes+n > opts.highWaterMark ) {
 			return null;
 		}
 		buf = new ArrayBuffer( n );
 
 		// Update the running counter of allocated bytes:
 		nbytes += n;
 
 		return buf;
 	}
 
 	/**
 	* Returns a typed array.
 	*
 	* @private
 	* @param {Function} ctor - typed array constructor
 	* @param {NonNegativeInteger} len - view length
 	* @param {string} dtype - data type
 	* @returns {(TypedArray|null)} typed array or null
 	*/
 	function typedarray( ctor, len, dtype ) {
 		var buf;
 		if ( len === 0 ) {
 			return new ctor( 0 );
 		}
 		buf = arraybuffer( ceil2( len )*BYTES_PER_ELEMENT[ dtype ] );
 		if ( buf === null ) {
 			return buf;
 		}
 		return new ctor( buf, 0, len );
 	}
 
 	/**
 	* Returns an uninitialized typed array.
 	*
 	* ## Notes
 	*
 	* -   Memory is **not** initialized.
 	* -   Memory is lazily allocated.
 	* -   If the function returns `null`, the function was unable to allocate a new typed array from the typed array pool (most likely due to insufficient memory).
 	*
 	* @private
 	* @param {(NonNegativeInteger|Collection)} [arg] - an array length or an array-like object
 	* @param {string} [dtype="float64"] - data type
 	* @throws {TypeError} must provide a valid array length or an array-like object
 	* @throws {TypeError} must provide a recognized data type
 	* @returns {(TypedArray|null)} typed array or null
 	*/
 	function malloc() {
 		var nargs;
 		var dtype;
 		var ctor;
 		var len;
 		var arr;
 		var out;
 		var i;
 
 		nargs = arguments.length;
 		if ( nargs && isString( arguments[ nargs-1 ] ) ) {
 			nargs -= 1;
 			dtype = arguments[ nargs ];
 		} else {
 			dtype = 'float64';
 		}
 		ctor = ctors( dtype );
 		if ( ctor === null ) {
 			throw new TypeError( 'invalid argument. Must provide a recognized data type. Value: `'+dtype+'`.' );
 		}
 		if ( nargs <= 0 ) {
 			return new ctor( 0 );
 		}
 		// Check if provided a typed array length...
 		if ( isNonNegativeInteger( arguments[ 0 ] ) ) {
 			return typedarray( ctor, arguments[ 0 ], dtype );
 		}
 		// Check if provided an array-like object containing data elements...
 		if ( isCollection( arguments[ 0 ] ) ) {
 			arr = arguments[ 0 ];
 			len = arr.length;
 			out = typedarray( ctor, len, dtype );
 			if ( out === null ) {
 				return out;
 			}
 			for ( i = 0; i < len; i++ ) {
 				out[ i ] = arr[ i ];
 			}
 			return out;
 		}
 		throw new TypeError( 'invalid argument. First argument must be either an array length or an array-like object. Value: `'+arguments[ 0 ]+'`.' );
 	}
 
 	/**
 	* Returns a zero-initialized typed array.
 	*
 	* ## Notes
 	*
 	* -   If the function returns `null`, the function was unable to allocate a new typed array from the typed array pool (most likely due to insufficient memory).
 	*
 	* @private
 	* @param {NonNegativeInteger} [len=0] - array length
 	* @param {string} [dtype="float64"] - data type
 	* @throws {TypeError} must provide a valid array length
 	* @throws {TypeError} must provide a recognized data type
 	* @returns {(TypedArray|null)} typed array or null
 	*/
 	function calloc() {
 		var nargs;
 		var out;
 		var i;
 
 		nargs = arguments.length;
 		if ( nargs === 0 ) {
 			out = malloc();
 		} else if ( nargs === 1 ) {
 			out = malloc( arguments[ 0 ] );
 		} else {
 			out = malloc( arguments[ 0 ], arguments[ 1 ] );
 		}
 		if ( out !== null ) {
 			// Initialize the memory...
 			for ( i = 0; i < out.length; i++ ) {
 				out[ i ] = 0.0;
 			}
 		}
 		return out;
 	}
 
 	/**
 	* Frees a typed array or typed array buffer.
 	*
 	* ## Notes
 	*
 	* -   Implicitly, we support providing non-internally allocated arrays and array buffer (e.g., "freeing" a typed array allocated in userland); however, the freed array buffer is likely to have excess capacity when compared to other members in its pool.
 	*
 	* @private
 	* @param {(TypedArray|ArrayBuffer)} buf - typed array or array buffer to free
 	* @throws {TypeError} must provide a typed array or typed array buffer
 	* @returns {boolean} boolean indicating whether the typed array or array buffer was successfully freed
 	*/
 	function free( buf ) {
 		var n;
 		var p;
 		var i;
 		if ( isTypedArrayLike( buf ) && buf.buffer ) {
 			buf = buf.buffer;
 		} else if ( !isArrayBuffer( buf ) ) {
 			throw new TypeError( 'invalid argument. Must provide a typed array or typed array buffer. Value: `'+buf+'`.' );
 		}
 		if ( buf.byteLength > 0 ) {
 			n = floor( log2( buf.byteLength ) );
 
 			// Prohibit "freeing" array buffers which would potentially allow users to circumvent high water mark limits:
 			n = min( pool.length-1, n );
 
 			// Ensure that we do not attempt to free the same buffer more than once...
 			p = pool[ n ];
 			for ( i = 0; i < p.length; i++ ) {
 				if ( p[ i ] === buf ) {
 					return false;
 				}
 			}
 			// Add the buffer to our pool of free buffers:
 			p.push( buf );
 		}
 		return true;
 	}
 
 	/**
 	* Clears the typed array pool allowing garbage collection of previously allocated (and currently free) array buffers.
 	*
 	* @private
 	*/
 	function clear() {
 		var i;
 		for ( i = 0; i < pool.length; i++ ) {
 			pool[ i ].length = 0;
 		}
 		nbytes = 0;
 	}
 }
 
 
 // EXPORTS //
 
 module.exports = factory;