infinity.memory¶

Provides a thread-safe shared memory within one INFINITY.JS instance.

All functions in this namespace read and write data to a shared memory in a thread-safe manner, by implicitly locking memory access (multiple-read, single-write). You can, however, also lock shared memory access explicitly, e.g. for grouping multiple read and/or write operations together, without other threads interfering with them. If you use the lock function to do so, always make sure that you unlock all namespaces you've locked, or otherwise your program will run into deadlocks and will not properly terminate (since the operating system will wait for it to release all locks it holds).

Note: if you are using the expiry parameter when putting data then make sure to call infinity.memory.flushExpired() in a regular interval (e.g. in a thread) so that expired values will be cleared.

Module: infinity.memory

Example:

infinity.loadModule('infinity.memory');

infinity.memory.lock('users');

try {
  infinity.memory.put('users', 'id:1', {id: 1, username: 'tf', name: 'Tobias Frie', email: 'recipientName@domain.com'});
  infinity.memory.putNumber('users', 'u:tf', 1);
  infinity.memory.putNumber('users', 'recipientName@domain.com', 1);
} finally {
  infinity.memory.unlock('users');
}

let id = infinity.memory.getNumber('users', 'u:tf');
console.debug(infinity.memory.get('users', 'id:' + id));

let cursor = new infinity.memory.cursor('users');

if (cursor.first()) {
  do {
    console.debug(cursor.key);
  } while (cursor.next());
}

cursor.free();

cursor¶

The cursor class serves, similar to database result set cursors, for orientation while iterating through the specified namespace. It points at the current row and can be moved forward, backward and be resetted to start and end positions. As long as the cursor object instance exists, the namespace remains locked.

Example:

infinity.loadModule('infinity.memory');
let myCursor = new infinity.memory.cursor('testNamespace');

Properties

key¶

Type: string

Gets the name of the key the curser is currently pointing at.

value¶

Type: any

Gets the value of the key the curser is currently pointing at.

valueAsBoolean¶

Type: boolean

Gets the value of the key the curser is currently pointing at as a boolean.

valueAsNumber¶

Type: number

Gets the value of the key the curser is currently pointing at as a number.

valueAsString¶

Type: string

Gets the value of the key the curser is currently pointing at as a string.

Methods

constructor()¶

Lets you create an INFINITY.JS memory cursor object instance.

Signature:

constructor( namespace: string )

Parameters:

• namespace: string

  The namespace to be read.

Example:

infinity.loadModule('infinity.memory');
let myCursor = new infinity.memory.cursor('testNamespace');

findFirst()¶

Searches for the first entry in memory the key of which starts with the specified characters and puts the cursor on its position.

Signature:

findFirst( key: string ): boolean

Parameters:

• key: string

  The key to be examined.

Return type: boolean

Example:

myCursor.findFirst('id:1');

findLast()¶

Searches for the last entry in memory the key of which starts with the specified characters and puts the cursor on its position.

Signature:

findLast( key: string ): boolean

Parameters:

• key: string

  The key to be examined.

Return type: boolean

Example:

myCursor.findLast('id:1');

findNext()¶

Can be used with findFirst() and findLast(): it searches for the next entry in memory, the key of which starts with the specified characters and puts the cursor on its position. If neither findFirst() nor findLast() has been used before the call of findNext(), the function behaves just like next().

Signature:

findNext(): boolean

Return type: boolean

Example:

infinity.loadModule('infinity.memory');

infinity.memory.lock('testNamespace');
infinity.memory.add('testNamespace', 'id:1', 'anyData')
infinity.memory.add('testNamespace', 'id:2', 'anyData')
infinity.memory.add('testNamespace', 'key:1', 'anyData')
infinity.memory.add('testNamespace', 'id:3', 'anyData')

let myCursor = new infinity.memory.cursor('testNamespace');

if (myCursor.findFirst('id:')) {
  do {
    console.debug(myCursor.key);
  } while (myCursor.findNext());
}
//id:1
//id:2
//id:3
myCursor.free();

findPrev()¶

Can be used with findFirst() and findLast(): it searches for the previous entry in memory, the key of which starts with the specified characters and puts the cursor on its position. If neither findFirst() nor findLast() has been used before the call of findPrev(), the function behaves just like prev().

Signature:

findPrev(): boolean

Return type: boolean

Example:

infinity.loadModule('infinity.memory');

infinity.memory.lock('testNamespace');
infinity.memory.add('testNamespace', 'id:1', 'anyData')
infinity.memory.add('testNamespace', 'id:2', 'anyData')
infinity.memory.add('testNamespace', 'key:1', 'anyData')
infinity.memory.add('testNamespace', 'id:3', 'anyData')

let myCursor = new infinity.memory.cursor('testNamespace');

if (myCursor.findLast('id:')) {
  do {
    console.debug(myCursor.key);
  } while (myCursor.findPrev());
}
//id:3
//id:2
//id:1
myCursor.free();

first()¶

Resets the cursor to the first position of the current namespace.

Signature:

first(): boolean

Return type: boolean

Example:

myCursor.first();

free()¶

Frees the memory previously occupied by the memory cursor object instance.

Signature:

free(): void

Example:

myCursor.free();

last()¶

Moves the cursor to the last position of the current namespace.

Signature:

last(): boolean

Return type: boolean

Example:

myCursor.last();

next()¶

Moves the cursor one entry forward.

Signature:

next(): boolean

Return type: boolean

Example:

myCursor.next();

prev()¶

Moves the cursor one entry backward.

Signature:

prev(): boolean

Return type: boolean

Example:

myCursor.prev();

listArray¶

Extends: Array<any>

An array of any elements.

add()¶

Writes the given data to the specified namespace and key in memory, only if there is no data yet.

Signature:

add( namespace: string, key: string, value: any, expire?: number ): boolean

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write at.

• value: any

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.add('testNamespace', 'id:1', 'anyData') ) {
  //...
}

addBoolean()¶

Writes a boolean value to the specified namespace and key in memory, only if there is no data yet.

Signature:

addBoolean( namespace: string, key: string, value: boolean, expire?: number ): boolean

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write at.

• value: boolean

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.addBoolean('testNamespace', 'id:1', true) ) {
  //...
}

addList()¶

Writes an array to the specified namespace and key in memory, only if there is no data yet.

Signature:

addList( namespace: string, key: string, value: any, expire?: number ): void

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write at.

• value: any

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.addList('testNamespace', 'id:1', [35, 'myStringData', true]);

addNumber()¶

Writes a number to the specified namespace and key in memory, only if there is no data yet.

Signature:

addNumber( namespace: string, key: string, value: number, expire?: number ): boolean

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write at.

• value: number

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.addNumber('testNamespace', 'id:1', 35) ) {
  //...
}

addString()¶

Writes a string to the specified namespace and key in memory, only if there is no data yet.

Signature:

addString( namespace: string, key: string, value: string, expire?: number ): boolean

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write at.

• value: string

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.addString('testNamespace', 'id:1', 'myStringData') ) {
  //...
}

clear()¶

Deletes all entries from the specified namespace.

Signature:

clear( namespace: string ): void

Parameters:

• namespace: string, optional

  The namespace to be cleared.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.clear('testNamespace');

decrement()¶

Decrements a counter inside the specified namespace and key and returns its value. The value starts at zero and may only be modified using ìncrement() and decrement() functions.

Signature:

decrement( namespace: string, key: string, value?: number ): number

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key which should contain the counter.

• value: number, optional

  Specifies the value to be substracted from the existing counter.

Return type: number

Example:

infinity.loadModule('infinity.memory');
let counter = infinity.memory.decrement('testNamespace', 'id:1');

delList()¶

Deletes the given value from the specified list stored in memory.

Signature:

delList( namespace: string, key: string, value: any, expire?: number ): boolean

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key containing the list to be altered.

• value: any

  The value to be deleted.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');

infinity.memory.lock('testNamespace');

infinity.memory.putList('testNamespace', 'id:1', [35, 'myStringData', true]);
infinity.memory.delList('testNamespace', 'id:1', 'myStringData');
console.debug(infinity.memory.getList('testNamespace', 'id:1'));
infinity.memory.unlock('testNamespace');
//[35,true]

dump()¶

Returns the contents of the specified namespace as an object.

Signature:

dump( namespace: string ): object

Parameters:

• namespace: string

  The namespace to be dumped.

Return type: object

Example:

infinity.loadModule('infinity.memory');
let contents = infinity.memory.dump('testNamespace');

exists()¶

Specifies whether the given key does exist in the specified namespace.

Signature:

exists( namespace: string, key: string, keyStart?: boolean ): boolean

Parameters:

• namespace: string

  The namespace to be examined.

• key: string

  The key being searched for.

• keyStart: boolean, optional

  Whether to search for any key that starts with the characters specified in "key".

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.exists('testNamespace', 'id:1') ) {
  //...
}

flushExpired()¶

Deletes entries from memory, which expiration timestamps have expired.

Signature:

flushExpired( namespace: string ): void

Parameters:

• namespace: string, optional

  The namespace to be flushed.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.flushExpired('testNamespace');

get()¶

Returns the value of the given key and namespace. Resets any expiration setting if present and if setUpdateExpireOnAccess() has not been set to false.

Signature:

get( namespace: string, key: string ): any

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to read from.

Return type: any

Example:

infinity.loadModule('infinity.memory');
let dataFromMemory = infinity.memory.get('testNamespace', 'id:1');

getBoolean()¶

Returns the boolean value of the specified namespace and key, if previously set with putBoolean(). Resets any expiration setting, if present and if setUpdateExpireOnAccess() has not been set to false.

Signature:

getBoolean( namespace: string, key: string ): boolean

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to read from.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
let booleanValueFromMemory = infinity.memory.getBoolean('testNamespace', 'id:1');

getCount()¶

Returns the amount of entries stored inside the specified namespace.

Signature:

getCount( namespace: string ): number

Parameters:

• namespace: string

  The namespace to be examined.

Return type: number

Example:

infinity.loadModule('infinity.memory');
let entriesInMemory = infinity.memory.getCount('testNamespace');

getList()¶

Returns the contents of the specified namespace inside a infinity.memory.listArray, if previously stored with put() or putList() . Resets any expiration settings, if present and if setUpdateExpireOnAccess() has not been set to false.

Signature:

getList( namespace: string, key: string ): infinity.memory.listArray

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to read from.

Return type: infinity.memory.listArray

Example:

infinity.loadModule('infinity.memory');
let listFromMemory = infinity.memory.getList('testNamespace', 'id:1');

getMaxSize()¶

Gets the maximum possible amount of entries for the specified namespace, if previously set by setMaxSize

Signature:

getMaxSize( namespace: string ): number

Parameters:

• namespace: string

  The namespace to specify the limit for.

Return type: number

Example:

infinity.loadModule('infinity.memory');
let namespaceMaxSize = infinity.memory.getMaxSize('testNamespace');

getNumber()¶

Returns the number value of the specified namespace and key, if previously set with putNumber(). Resets any expiration settings, if present and if setUpdateExpireOnAccess() has not been set to false.

Signature:

getNumber( namespace: string, key: string ): number

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to read from.

Return type: number

Example:

infinity.loadModule('infinity.memory');
let numberFromMemory = infinity.memory.getNumber('testNamespace', 'id:1');

getSize()¶

Returns the bytesize of the namespace.

Signature:

getSize( namespace: string ): number

Parameters:

• namespace: string

  The namespace to be examined.

Return type: number

Example:

infinity.loadModule('infinity.memory');
let size = infinity.memory.getSize('testNamespace');

getString()¶

Returns the string contents of the specified namespace and key, if previously set with putString(). Resets any expiration settings, if present and if setUpdateExpireOnAccess() has not been set to false.

Signature:

getString( namespace: string, key: string ): string

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to read from.

Return type: string

Example:

infinity.loadModule('infinity.memory');
let stringFromMemory = infinity.memory.getString('testNamespace', 'id:1');

getUpdateExpireOnAccess()¶

Gets the value set by setUpdateExpireOnAccess().

Signature:

getUpdateExpireOnAccess( namespace: string ): boolean

Parameters:

• namespace: string

  The namespace to be examined.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.getUpdateExpireOnAccess('testNamespace') ) {
  //...
}

increment()¶

Increments a counter inside the specified namespace and key and returns its value. The value starts at zero and may only be modified using ìncrement() and decrement() functions.

Signature:

increment( namespace: string, key: string, value?: number ): number

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key which should contain the counter.

• value: number, optional

  Specifies the value to be added to the existing value.

Return type: number

Example:

infinity.loadModule('infinity.memory');
let counter = infinity.memory.increment('testNamespace', 'id:1');

lock()¶

Locks the namespace for reading and/or writing. Locking a namespace for read-only access will halt script execution until there is no other thread holding a write-lock on that same namespace. There can be multiple read-only locks by different threads at the same time, but only one write-lock. Locking a namespace for write access will halt script execution until there is no other thread holding a read- or write-lock on that same namespace.

This method can be used to ensure atomic operations on shared memory without threads interfering with each other (much like transactions in a database).

Note: all infinity.memory functions are thread-safe, but if you need to read and/or write multiple values without another thread changing data in between, then you can use the lock method to explicitly lock a certain namespace.

Attention: you must always unlock a namespace you have locked. Otherwise you will block all other threads, and in addition to that, your program will not terminate correctly, since the operating system will wait for your program to release all locks it holds. Therefore you should always use try-finally blocks to ensure you release your locks.

Signature:

lock( namespace: string, readOnly?: boolean ): boolean

Parameters:

• namespace: string

  The namespace to be locked.

• readOnly: boolean, optional

  Whether to lock the namespace for reading only.

Return type: boolean

Example:

infinity.loadModule('infinity.memory');
if ( infinity.memory.lock(namespace) ) { // lock namespace
  try {
    //...
  } finally {
    infinity.memory.unlock(namespace); // always unlock the namespace
  }
}

put()¶

Writes the given data to the specified namespace and key in memory, overwriting any data previously stored there.

Signature:

put( namespace: string, key: string, value: any, expire?: number ): void

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write to.

• value: any

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.put('testNamespace', 'id:1', 'anyData');

putBoolean()¶

Writes a boolean value to the specified namespace and key in memory, overwriting any data previously stored there. The stored value can only be read with getBoolean().

Signature:

putBoolean( namespace: string, key: string, value: boolean, expire?: number ): void

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write to.

• value: boolean

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.putBoolean('testNamespace', 'id:1', true);

putList()¶

Writes a infinity.memory.listArray to the specified namespace and key in memory, overwriting any data previously stored there. The stored value can only be read with getList().

Signature:

putList( namespace: string, key: string, value: infinity.memory.listArray, expire?: number ): void

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write to.

• value: infinity.memory.listArray

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.putList('testNamespace', 'id:1', [35, 'myStringData', true]);

putNumber()¶

Writes a number to the specified namespace and key in memory, overwriting any data previously stored there. The stored value can only be read with getNumber().

Signature:

putNumber( namespace: string, key: string, value: number, expire?: number ): void

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write to.

• value: number

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.putNumber('testNamespace', 'id:1', 35);

putString()¶

Writes a string to the specified namespace and key in memory, overwriting any data previously stored there. The stored value can only be read with getString().

Signature:

putString( namespace: string, key: string, value: string, expire?: number ): void

Parameters:

• namespace: string

  The namespace to operate in.

• key: string

  The key to write to.

• value: string

  The value to write.

• expire: number, optional

  The amount of seconds for the entry to be valid.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.putString('testNamespace', 'id:1', 'myStringData');

remove()¶

Removes the given key inside the specified namespace.

Signature:

remove( namespace: string, key: string, keyStart?: boolean ): void

Parameters:

• namespace: string

  The namespace to remove the key from.

• key: string

  The key to remove.

• keyStart: boolean, optional

  Whether to remove any key that starts with the characters specified in "key".

Example:

infinity.loadModule('infinity.memory');
infinity.memory.remove('testNamespace', 'id:1');

setMaxSize()¶

Sets the maximum count of the entries for the specified namespace to hold.

Signature:

setMaxSize( namespace: string, value: number ): void

Parameters:

• namespace: string

  The namespace to be limited.

• value: number

  The amount of the entries not to be exceeded.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.setMaxSize('testNamespace', 30);

setUpdateExpireOnAccess()¶

Sets whether the expiration settings inside the memory entries should be reset on access to them. The default setting is true.

Signature:

setUpdateExpireOnAccess( namespace: string, value: boolean ): void

Parameters:

• namespace: string

  The namespace for the setting to take effect.

• value: boolean

  true for resetting the expiration settings on access, false for keeping them in effect.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.setUpdateExpireOnAccess('testNamespace', false);

unlock()¶

Unlocks the namespace, allowing other threads to access it.

Signature:

unlock( namespace: string ): void

Parameters:

• namespace: string

  The namespace to be unlocked.

Example:

infinity.loadModule('infinity.memory');
infinity.memory.unlock('testNamespace');