stdlib-js/array-poolPublic

NotificationsYou must be signed in to change notification settings
Fork1
Star5

Typed array pool.

License

Apache-2.0 license

5 stars 1 fork Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 195 Commits
CONTRIBUTORS		CONTRIBUTORS
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
mod.d.ts		mod.d.ts
mod.js		mod.js
mod.js.map		mod.js.map
package.json		package.json
stats.html		stats.html

Repository files navigation

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please considerfinancially supporting stdlib. We greatly appreciate your continued support!

typedarraypool

Allocate typed arrays from a typed array memory pool.

Usage

importtypedarraypoolfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-pool@deno/mod.js';

You can also import the following named exports from the package:

import{factory}from'https://cdn.jsdelivr.net/gh/stdlib-js/array-pool@deno/mod.js';

typedarraypool( [dtype] )

Returns anuninitializedtyped array having a specifieddata typedtype.

vararr=typedarraypool();// returns <Float64Array>[]// ...typedarraypool.free(arr);

By default, the outputtyped array isfloat64. To specify an alternativedata type, set thedtype parameter.

vararr=typedarraypool('int32');// returns <Int32Array>[]// ...typedarraypool.free(arr);

typedarraypool( length[, dtype] )

Returns anuninitializedtyped array having a specifiedlength from atyped array memory pool.

vararr1=typedarraypool(5);// returns <Float64Array>vararr2=typedarraypool(5,'uint8');// returns <Uint8Array>// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool( typedarray[, dtype] )

Returns a pooledtyped array from anothertyped array.

vararr1=typedarraypool([5.0,-3.0,2.0]);// returns <Float64Array>[ 5.0, -3.0, 2.0 ]vararr2=typedarraypool(arr1);// returns <Float64Array>[ 5.0, -3.0, 2.0 ]vararr3=typedarraypool(arr1,'int32');// returns <Int32Array>[ 5, -3, 2 ]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);typedarraypool.free(arr3);

typedarraypool( obj[, dtype] )

Returns a pooledtyped array from an array-likeobject.

vararr1=typedarraypool([0.5,0.5,0.5]);// returns <Float64Array>[ 0.5, 0.5, 0.5 ]vararr2=typedarraypool([0.5,0.5,0.5],'float32');// returns <Float32Array>[ 0.5, 0.5, 0.5 ]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool.malloc( [dtype] )

Returns anuninitializedtyped array having a specifieddata typedtype.

vararr1=typedarraypool.malloc();// returns <Float64Array>[]vararr2=typedarraypool.malloc('int32');// returns <Int32Array>[]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool.malloc( length[, dtype] )

Returns anuninitializedtyped array having a specifiedlength from atyped array memory pool.

vararr1=typedarraypool.malloc(5);// returns <Float64Array>vararr2=typedarraypool.malloc(5,'uint8');// returns <Uint8Array>// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool.malloc( typedarray[, dtype] )

Returns a pooledtyped array from anothertyped array.

vararr1=typedarraypool.malloc([5.0,-3.0,2.0]);// returns <Float64Array>[ 5.0, -3.0, 2.0 ]vararr2=typedarraypool.malloc(arr1);// returns <Float64Array>[ 5.0, -3.0, 2.0 ]vararr3=typedarraypool.malloc(arr1,'int32');// returns <Int32Array>[ 5, -3, 2 ]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);typedarraypool.free(arr3);

typedarraypool.malloc( obj[, dtype] )

Returns a pooledtyped array from an array-likeobject.

vararr1=typedarraypool.malloc([0.5,0.5,0.5]);// returns <Float64Array>[ 0.5, 0.5, 0.5 ]vararr2=typedarraypool.malloc([0.5,0.5,0.5],'float32');// returns <Float32Array>[ 0.5, 0.5, 0.5 ]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool.calloc( [dtype] )

Returns azero-initializedtyped array having a specifieddata typedtype.

vararr1=typedarraypool.calloc();// returns <Float64Array>[]vararr2=typedarraypool.calloc('int32');// returns <Int32Array>[]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool.calloc( length[, dtype] )

Returns azero-initializedtyped array having a specifiedlength from atyped array memory pool.

vararr1=typedarraypool.calloc(5);// returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 0.0 ]vararr2=typedarraypool.calloc(5,'uint8');// returns <Uint8Array>[ 0, 0, 0, 0, 0 ]// ...typedarraypool.free(arr1);typedarraypool.free(arr2);

typedarraypool.free( buf )

Frees atyped array or typed arraybuffer for use in a future allocation.

vararr=typedarraypool(10,'float64');// returns <Float64Array>// ...// Free the allocated typed array for use in a future allocation:typedarraypool.free(arr);// Create another typed array:arr=typedarraypool(10,'float64');// returns <Float64Array>// ...// Free the allocated typed array buffer for use in a future allocation:typedarraypool.free(arr.buffer);

typedarraypool.clear()

Clears thetyped array pool allowing garbage collection of previously allocated (and currently free)array buffers.

vararr=typedarraypool(10,'float64');// returns <Float64Array>// ...typedarraypool.free(arr);// ...// Clear all freed buffers:typedarraypool.clear();

typedarraypool.highWaterMark

Read-only property returning the pool's high water mark (in bytes).

varlimit=typedarraypool.highWaterMark;// returns <number>

Once a high water mark is reached,typed array allocationfails.

typedarraypool.nbytes

Read-only property returning the total number of allocated bytes.

vararr=typedarraypool(5,'float64');varnbytes=typedarraypool.nbytes;// returns <number>

The returned value is the totalaccumulated value. Hence, anytime a pool must allocate a newarray buffer (i.e., more memory), the pool increments this value. The only time this value is decremented is when a pool is cleared. This behavior means that, while allocated buffers which are never freed may, in fact, be garbage collected, they continue to count against the high water mark limit. Accordingly, you shouldalways free allocated buffers in order to prevent the pool from believing that non-freed buffers are continually in use.

typedarraypool.factory( [options] )

Creates a newtyped array pool.

varpool=typedarraypool.factory();vararr=pool(5,'float64');// returns <Float64Array>// ...pool.free(arr);

The method accepts the followingoptions:

highWaterMark: maximum total memory (in bytes) which can be allocated. Default:2^53 bytes.

By default, the maximum total memory a pool may allocate is2^53 bytes (approximately1 petabyte, which, in practical terms, means a pool hasunlimited capacity). To specify an alternative limit, set thehighWaterMark option.

// Create a new typed array pool which can allocate up to 1MB:varpool=typedarraypool.factory({'highWaterMark':1e6});vararr=pool(5,'float64');// returns <Float64Array>// ...pool.free(arr);

Notes

Uninitialized typed arrays may contain sensitive contents. If security is paramount (e.g., if freedtyped arrays have been used to store sensitive contents), usecalloc.
An allocatedtyped array isguaranteed to have an underlyingarray buffer withat leastN * w bytes, whereN is the number oftyped array elements andw is the number of bytes per element. Note, however, that the underlyingarray buffer is likely to haveexcess capacity. Thus, if you create manytyped arrays which are held in memory and arenot freed, you are likely to consume significantly more memory than if you had directly usedtyped array constructors. However, if you create manytyped arrays which are rapidly discarded and of relatively large size, then using atyped array pool can offer significant performance advantages.

Examples

importrandufrom'https://cdn.jsdelivr.net/gh/stdlib-js/random-base-randu@deno/mod.js';importtypedarraypoolfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-pool@deno/mod.js';// Create a typed array pool which can allocate at most 1GB:vartypedarray=typedarraypool.factory({'highWaterMark':1e9});// Inspect the pool:console.log('Max bytes: %d',typedarray.highWaterMark);console.log('nbytes: %d',typedarray.nbytes);// Allocate an array for storing double-precision floating-point numbers:vararr1=typedarray(5,'float64');// returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 0.0 ]// Inspect the pool:console.log('nbytes: %d',typedarray.nbytes);// Fill the array...vari;for(i=0;i<arr1.length;i++){arr1[i]=randu();}// Inspect array contents:console.log(arr1);// Free the array:typedarray.free(arr1);// Allocate another array similar to the previous one:vararr2=typedarray(5,'float64');// returns <Float64Array>// Check that we have been returned a new typed array view:console.log(arr2===arr1);// => false// Inspect array contents:console.log(arr2);// Free the array:typedarray.free(arr2);// Allocate an initialized array:vararr3=typedarray.calloc(5,'float64');// returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 0.0 ]// Inspect array contents:console.log(arr3);// Free the array:typedarray.free(arr3);// Clear the pool:typedarray.clear();// Inspect the pool:console.log('nbytes: %d',typedarray.nbytes);

Notice

This package is part ofstdlib, a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to developstdlib, see the main projectrepository.