base/frameworks/broker/store.zeek

Broker

The Broker-based data store API and its various options.

Namespace

Broker

Imports

base/bif/data.bif.zeek, base/bif/store.bif.zeek, base/frameworks/broker/main.zeek

Summary

Redefinable Options

Broker::default_clone_mutation_buffer_interval: interval &redef

The maximum amount of time that a disconnected clone will buffer data store mutation commands.

Broker::default_clone_resync_interval: interval &redef

The default frequency at which clones will attempt to reconnect/resynchronize with their master in the event that they become disconnected.

Broker::default_clone_stale_interval: interval &redef

The duration after which a clone that is disconnected from its master will begin to treat its local cache as stale.

Broker::table_store_db_directory: string &redef

The directory used for storing persistent database files when using Broker store backed Zeek tables.

Broker::table_store_master: bool &redef

If set to true, the current node is the master node for Broker stores backing Zeek tables.

Types

Broker::BackendOptions: record

Options to tune the particular storage backends.

Broker::BackendType: enum

Enumerates the possible storage backends.

Broker::QueryResult: record

The result of a data store query.

Broker::QueryStatus: enum

Whether a data store query could be completed or not.

Broker::SQLiteFailureMode: enum

Behavior when the SQLite database file is found to be corrupt or otherwise fails to open or initialize.

Broker::SQLiteJournalMode: enum

Values supported for SQLite’s PRAGMA journal_mode statement.

Broker::SQLiteOptions: record

Options to tune the SQLite storage backend.

Broker::SQLiteSynchronous: enum

Values supported for SQLite’s PRAGMA synchronous statement.

Functions

Broker::append: function

Extends an existing string with another.

Broker::clear: function

Deletes all of a store’s content, it will be empty afterwards.

Broker::close: function

Close a data store.

Broker::create_clone: function

Create a clone of a master data store which may live with a remote peer.

Broker::create_master: function

Create a master data store which contains key-value pairs.

Broker::data: function

Convert any Zeek value to communication data.

Broker::data_type: function

Retrieve the type of data associated with communication data.

Broker::decrement: function

Decrements an existing value by a given amount.

Broker::erase: function

Remove a key-value pair from the store.

Broker::exists: function

Check if a key exists in a data store.

Broker::get: function

Lookup the value associated with a key in a data store.

Broker::get_index_from_value: function

Retrieve a specific index from an existing container value.

Broker::increment: function

Increments an existing value by a given amount.

Broker::insert_into_set: function

Inserts an element into an existing set.

Broker::insert_into_table: function

Inserts an element into an existing table.

Broker::is_closed: function

Check if a store is closed or not.

Broker::keys: function

Returns a set with all of a store’s keys.

Broker::pop: function

Removes the last element of an existing vector.

Broker::push: function

Appends an element to an existing vector.

Broker::put: function

Insert a key-value pair into the store.

Broker::put_unique: function

Insert a key-value pair into the store, but only if the key does not already exist.

Broker::record_assign: function

Replace a field in a record at a particular position.

Broker::record_create: function

Create communication data of type “record”.

Broker::record_iterator: function

Create an iterator for a record.

Broker::record_iterator_last: function

Check if there are no more elements to iterate over.

Broker::record_iterator_next: function

Advance an iterator.

Broker::record_iterator_value: function

Retrieve the data at an iterator’s current position.

Broker::record_lookup: function

Lookup a field in a record at a particular position.

Broker::record_size: function

Get the number of fields within a record.

Broker::remove_from: function

Removes an element from an existing set or table.

Broker::set_clear: function

Remove all elements within a set.

Broker::set_contains: function

Check if a set contains a particular element.

Broker::set_create: function

Create communication data of type “set”.

Broker::set_insert: function

Insert an element into a set.

Broker::set_iterator: function

Create an iterator for a set.

Broker::set_iterator_last: function

Check if there are no more elements to iterate over.

Broker::set_iterator_next: function

Advance an iterator.

Broker::set_iterator_value: function

Retrieve the data at an iterator’s current position.

Broker::set_remove: function

Remove an element from a set.

Broker::set_size: function

Get the number of elements within a set.

Broker::store_name: function

Get the name of a store.

Broker::table_clear: function

Remove all elements within a table.

Broker::table_contains: function

Check if a table contains a particular key.

Broker::table_create: function

Create communication data of type “table”.

Broker::table_insert: function

Insert a key-value pair into a table.

Broker::table_iterator: function

Create an iterator for a table.

Broker::table_iterator_last: function

Check if there are no more elements to iterate over.

Broker::table_iterator_next: function

Advance an iterator.

Broker::table_iterator_value: function

Retrieve the data at an iterator’s current position.

Broker::table_lookup: function

Retrieve a value from a table.

Broker::table_remove: function

Remove a key-value pair from a table.

Broker::table_size: function

Get the number of elements within a table.

Broker::vector_clear: function

Remove all elements within a vector.

Broker::vector_create: function

Create communication data of type “vector”.

Broker::vector_insert: function

Insert an element into a vector at a particular position, possibly displacing existing elements (insertion always grows the size of the vector by one).

Broker::vector_iterator: function

Create an iterator for a vector.

Broker::vector_iterator_last: function

Check if there are no more elements to iterate over.

Broker::vector_iterator_next: function

Advance an iterator.

Broker::vector_iterator_value: function

Retrieve the data at an iterator’s current position.

Broker::vector_lookup: function

Lookup an element in a vector at a particular position.

Broker::vector_remove: function

Remove an element from a vector at a particular position.

Broker::vector_replace: function

Replace an element in a vector at a particular position.

Broker::vector_size: function

Get the number of elements within a vector.

Detailed Interface

Redefinable Options

Broker::default_clone_mutation_buffer_interval
Type

interval

Attributes

&redef

Default

2.0 mins

The maximum amount of time that a disconnected clone will buffer data store mutation commands. If the clone reconnects before this time, it will replay all stored commands. Note that this doesn’t completely prevent the loss of store updates: all mutation messages are fire-and-forget and not explicitly acknowledged by the master. A negative/zero value indicates to never buffer commands.

Broker::default_clone_resync_interval
Type

interval

Attributes

&redef

Default

10.0 secs

The default frequency at which clones will attempt to reconnect/resynchronize with their master in the event that they become disconnected.

Broker::default_clone_stale_interval
Type

interval

Attributes

&redef

Default

5.0 mins

The duration after which a clone that is disconnected from its master will begin to treat its local cache as stale. In the stale state, queries to the cache will timeout. A negative value indicates that the local cache is never treated as stale.

Broker::table_store_db_directory
Type

string

Attributes

&redef

Default

"."

The directory used for storing persistent database files when using Broker store backed Zeek tables.

Broker::table_store_master
Type

bool

Attributes

&redef

Default

T

If set to true, the current node is the master node for Broker stores backing Zeek tables. By default this value will be automatically set to true in standalone mode, and on the manager node of a cluster. This value should not typically be changed manually.

Types

Broker::BackendOptions
Type

record

sqlite: Broker::SQLiteOptions &default = [path=, synchronous=<uninitialized>, journal_mode=<uninitialized>, failure_mode=Broker::SQLITE_FAILURE_MODE_FAIL, integrity_check=F] &optional

Options to tune the particular storage backends.

Broker::BackendType
Type

enum

Broker::MEMORY
Broker::SQLITE

Enumerates the possible storage backends.

Broker::QueryResult
Type

record

status: Broker::QueryStatus

Whether the query completed or not.

result: Broker::Data

The result of the query. Certain queries may use a particular data type (e.g. querying store size always returns a count, but a lookup may return various data types).

The result of a data store query.

Broker::QueryStatus
Type

enum

Broker::SUCCESS
Broker::FAILURE

Whether a data store query could be completed or not.

Broker::SQLiteFailureMode
Type

enum

Broker::SQLITE_FAILURE_MODE_FAIL

Fail during initialization.

Broker::SQLITE_FAILURE_MODE_DELETE

Attempt to delete the database file and retry.

Behavior when the SQLite database file is found to be corrupt or otherwise fails to open or initialize.

Broker::SQLiteJournalMode
Type

enum

Broker::SQLITE_JOURNAL_MODE_DELETE
Broker::SQLITE_JOURNAL_MODE_WAL

Values supported for SQLite’s PRAGMA journal_mode statement.

Broker::SQLiteOptions
Type

record

path: string &default = "" &optional

File system path of the database. If left empty, will be derived from the name of the store, and use the ‘.sqlite’ file suffix.

synchronous: Broker::SQLiteSynchronous &optional

If set, runs the PRAGMA synchronous statement with the provided value after connecting to the SQLite database. See SQLite’s synchronous documentation for more details around performance and data safety trade offs.

journal_mode: Broker::SQLiteJournalMode &optional

If set, runs the PRAGMA journal_mode statement with the provided value after connecting to the SQLite database. See SQLite’s journal_mode documentation for more details around performance, data safety trade offs and interaction with the PRAGMA synchronous statement.

failure_mode: Broker::SQLiteFailureMode &default = Broker::SQLITE_FAILURE_MODE_FAIL &optional

What to do when the database is found corrupt during initialization. When set to SQLITE_FAILURE_MODE_DELETE, the old file is deleted to allow creation of a new and empty database. By default, an error is reported, the corrupt database file left in place and the data store is in a non-functional state.

integrity_check: bool &default = F &optional

When true, run the PRAGMA integrity_check statement after opening the database and fail according to failure_mode. PRAGMA integrity_check may take a non-negligible amount of time, so you are advised to experiment with the expected sizes of your databases if that is acceptable. Corrupted databases should be reliably detected when this setting is T.

Options to tune the SQLite storage backend.

Broker::SQLiteSynchronous
Type

enum

Broker::SQLITE_SYNCHRONOUS_OFF
Broker::SQLITE_SYNCHRONOUS_NORMAL
Broker::SQLITE_SYNCHRONOUS_FULL
Broker::SQLITE_SYNCHRONOUS_EXTRA

Values supported for SQLite’s PRAGMA synchronous statement.

Functions

Broker::append
Type

function (h: opaque of Broker::Store, k: any, s: string, e: interval &default = 0 secs &optional) : bool

Extends an existing string with another.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • s – the string to append.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::clear
Type

function (h: opaque of Broker::Store) : bool

Deletes all of a store’s content, it will be empty afterwards.

Returns

false if the store handle was not valid.

Broker::close
Type

function (h: opaque of Broker::Store) : bool

Close a data store.

Parameters

h – a data store handle.

Returns

true if store was valid and is now closed. The handle can no longer be used for data store operations.

Broker::create_clone
Type

function (name: string, resync_interval: interval &default = Broker::default_clone_resync_interval &optional, stale_interval: interval &default = Broker::default_clone_stale_interval &optional, mutation_buffer_interval: interval &default = Broker::default_clone_mutation_buffer_interval &optional) : opaque of Broker::Store

Create a clone of a master data store which may live with a remote peer. A clone automatically synchronizes to the master by receiving modifications and applying them locally. Direct modifications are not possible, they must be sent through the master store, which then automatically broadcasts the changes out to clones. But queries may be made directly against the local cloned copy, which may be resolved quicker than reaching out to a remote master store.

Parameters
  • name – the unique name which identifies the master data store.

  • resync_interval – the frequency at which a clone that is disconnected from its master attempts to reconnect with it.

  • stale_interval – the duration after which a clone that is disconnected from its master will begin to treat its local cache as stale. In this state, queries to the clone will timeout. A negative value indicates that the local cache is never treated as stale.

  • mutation_buffer_interval – the amount of time to buffer data store update messages once a clone detects its master is unavailable. If the clone reconnects before this time, it will replay all buffered commands. Note that this doesn’t completely prevent the loss of store updates: all mutation messages are fire-and-forget and not explicitly acknowledged by the master. A negative/zero value indicates that commands never buffer.

Returns

a handle to the data store for which a subsequent call to Broker::is_closed will return true if the store could not be created/opened.

Broker::create_master
Type

function (name: string, b: Broker::BackendType &default = Broker::MEMORY &optional, options: Broker::BackendOptions &default = [sqlite=[path=, synchronous=<uninitialized>, journal_mode=<uninitialized>, failure_mode=Broker::SQLITE_FAILURE_MODE_FAIL, integrity_check=F]] &optional) : opaque of Broker::Store

Create a master data store which contains key-value pairs.

Parameters
  • name – a unique name for the data store.

  • b – the storage backend to use.

  • options – tunes how some storage backends operate.

Returns

a handle to the data store for which a subsequent call to Broker::is_closed will return true if the store could not be created/opened.

Broker::data
Type

function (d: any) : Broker::Data

Convert any Zeek value to communication data.

Note

Normally you won’t need to use this function as data conversion happens implicitly when passing Zeek values into Broker functions.

Parameters

d – any Zeek value to attempt to convert (not all types are supported).

Returns

the converted communication data. If the supplied Zeek data type does not support conversion to communication data, the returned record’s optional field will not be set.

Broker::data_type
Type

function (d: Broker::Data) : Broker::DataType

Retrieve the type of data associated with communication data.

Parameters

d – the communication data.

Returns

The data type associated with the communication data. Note that Broker represents records in the same way as vectors, so there is no “record” type.

Broker::decrement
Type

function (h: opaque of Broker::Store, k: any, a: any &default = 1 &optional, e: interval &default = 0 secs &optional) : bool

Decrements an existing value by a given amount. This is supported for all numerical types, as well as for timestamps.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • amount – the amount to decrement the value by.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::erase
Type

function (h: opaque of Broker::Store, k: any) : bool

Remove a key-value pair from the store.

Parameters
  • h – the handle of the store to modify.

  • k – the key to remove.

Returns

false if the store handle was not valid.

Broker::exists
Type

function (h: opaque of Broker::Store, k: any) : Broker::QueryResult

Check if a key exists in a data store.

Parameters
  • h – the handle of the store to query.

  • k – the key to lookup.

Returns

True if the key exists in the data store.

Broker::get
Type

function (h: opaque of Broker::Store, k: any) : Broker::QueryResult

Lookup the value associated with a key in a data store.

Parameters
  • h – the handle of the store to query.

  • k – the key to lookup.

Returns

the result of the query.

Broker::get_index_from_value
Type

function (h: opaque of Broker::Store, k: any, i: any) : Broker::QueryResult

Retrieve a specific index from an existing container value. This is supported for values of types set, table, and vector.

Parameters
  • h – the handle of the store to query.

  • k – the key of the container value to lookup.

  • i – the index to retrieve from the container value.

Returns

For tables and vectors, the value at the given index, or failure if the index doesn’t exist. For sets, a boolean indicating whether the index exists. Returns failure if the key does not exist at all.

Broker::increment
Type

function (h: opaque of Broker::Store, k: any, a: any &default = 1 &optional, e: interval &default = 0 secs &optional) : bool

Increments an existing value by a given amount. This is supported for all numerical types, as well as for timestamps.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • a – the amount to increment the value by.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::insert_into_set
Type

function (h: opaque of Broker::Store, k: any, i: any, e: interval &default = 0 secs &optional) : bool

Inserts an element into an existing set.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • i – the index to insert into the set.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::insert_into_table
Type

function (h: opaque of Broker::Store, k: any, i: any, v: any, e: interval &default = 0 secs &optional) : bool

Inserts an element into an existing table.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • i – the index to insert into the table

  • v – the value to associate with the index.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::is_closed
Type

function (h: opaque of Broker::Store) : bool

Check if a store is closed or not.

Returns

true if the store is closed.

Broker::keys
Type

function (h: opaque of Broker::Store) : Broker::QueryResult

Returns a set with all of a store’s keys. The results reflect a snapshot in time that may diverge from reality soon afterwards. When accessing any of the element, it may no longer actually be there. The function is also expensive for large stores, as it copies the complete set.

Returns

a set with the keys. If you expect the keys to be of non-uniform type, consider using Broker::set_iterator to iterate over the result.

Broker::pop
Type

function (h: opaque of Broker::Store, k: any, e: interval &default = 0 secs &optional) : bool

Removes the last element of an existing vector.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::push
Type

function (h: opaque of Broker::Store, k: any, v: any, e: interval &default = 0 secs &optional) : bool

Appends an element to an existing vector.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • b – the value to append to the vector.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::put
Type

function (h: opaque of Broker::Store, k: any, v: any, e: interval &default = 0 secs &optional) : bool

Insert a key-value pair into the store.

Parameters
  • h – the handle of the store to modify.

  • k – the key to insert.

  • v – the value to insert.

  • e – the expiration interval of the key-value pair.

Returns

false if the store handle was not valid.

Broker::put_unique
Type

function (h: opaque of Broker::Store, k: any, v: any, e: interval &default = 0 secs &optional) : Broker::QueryResult

Insert a key-value pair into the store, but only if the key does not already exist.

Parameters
  • h – the handle of the store to modify.

  • k – the key to insert.

  • v – the value to insert.

  • e – the expiration interval of the key-value pair.

Returns

the result of the query which is a boolean data value that is true if the insertion happened, or false if it was rejected due to the key already existing.

Broker::record_assign
Type

function (r: Broker::Data, idx: count, d: any) : bool

Replace a field in a record at a particular position.

Parameters
  • r – the record to modify.

  • d – the new field value to assign.

  • idx – the index to replace.

Returns

false if the index was larger than any valid index, else true.

Broker::record_create
Type

function (sz: count) : Broker::Data

Create communication data of type “record”.

Parameters

sz – the number of fields in the record.

Returns

record data, with all fields uninitialized.

Broker::record_iterator
Type

function (r: Broker::Data) : opaque of Broker::RecordIterator

Create an iterator for a record. Note that this makes a copy of the record internally to ensure the iterator is always valid.

Parameters

r – the record to iterate over.

Returns

an iterator.

Broker::record_iterator_last
Type

function (it: opaque of Broker::RecordIterator) : bool

Check if there are no more elements to iterate over.

Parameters

it – an iterator.

Returns

true if there are no more elements to iterator over, i.e. the iterator is one-past-the-final-element.

Broker::record_iterator_next
Type

function (it: opaque of Broker::RecordIterator) : bool

Advance an iterator.

Parameters

it – an iterator.

Returns

true if the iterator, after advancing, still references an element in the collection. False if the iterator, after advancing, is one-past-the-final-element.

Broker::record_iterator_value
Type

function (it: opaque of Broker::RecordIterator) : Broker::Data

Retrieve the data at an iterator’s current position.

Parameters

it – an iterator.

Returns

element in the collection that the iterator currently references.

Broker::record_lookup
Type

function (r: Broker::Data, idx: count) : Broker::Data

Lookup a field in a record at a particular position.

Parameters
  • r – the record to query.

  • idx – the index to lookup.

Returns

the value at the index. The optional field of the returned record may not be set if the field of the record has no value or if the index was not valid.

Broker::record_size
Type

function (r: Broker::Data) : count

Get the number of fields within a record.

Parameters

r – the record to query.

Returns

the number of fields in the record.

Broker::remove_from
Type

function (h: opaque of Broker::Store, k: any, i: any, e: interval &default = 0 secs &optional) : bool

Removes an element from an existing set or table.

Parameters
  • h – the handle of the store to modify.

  • k – the key whose associated value is to be modified. The key must already exist.

  • i – the index to remove from the set or table.

  • e – the new expiration interval of the modified key. If null, the current expiration time isn’t changed.

Returns

false if the store handle was not valid.

Broker::set_clear
Type

function (s: Broker::Data) : bool

Remove all elements within a set.

Parameters

s – the set to clear.

Returns

always true.

Broker::set_contains
Type

function (s: Broker::Data, key: any) : bool

Check if a set contains a particular element.

Parameters
  • s – the set to query.

  • key – the element to check for existence.

Returns

true if the key exists in the set.

Broker::set_create
Type

function () : Broker::Data

Create communication data of type “set”.

Broker::set_insert
Type

function (s: Broker::Data, key: any) : bool

Insert an element into a set.

Parameters
  • s – the set to modify.

  • key – the element to insert.

Returns

true if the key was inserted, or false if it already existed.

Broker::set_iterator
Type

function (s: Broker::Data) : opaque of Broker::SetIterator

Create an iterator for a set. Note that this makes a copy of the set internally to ensure the iterator is always valid.

Parameters

s – the set to iterate over.

Returns

an iterator.

Broker::set_iterator_last
Type

function (it: opaque of Broker::SetIterator) : bool

Check if there are no more elements to iterate over.

Parameters

it – an iterator.

Returns

true if there are no more elements to iterator over, i.e. the iterator is one-past-the-final-element.

Broker::set_iterator_next
Type

function (it: opaque of Broker::SetIterator) : bool

Advance an iterator.

Parameters

it – an iterator.

Returns

true if the iterator, after advancing, still references an element in the collection. False if the iterator, after advancing, is one-past-the-final-element.

Broker::set_iterator_value
Type

function (it: opaque of Broker::SetIterator) : Broker::Data

Retrieve the data at an iterator’s current position.

Parameters

it – an iterator.

Returns

element in the collection that the iterator currently references.

Broker::set_remove
Type

function (s: Broker::Data, key: any) : bool

Remove an element from a set.

Parameters
  • s – the set to modify.

  • key – the element to remove.

Returns

true if the element existed in the set and is now removed.

Broker::set_size
Type

function (s: Broker::Data) : count

Get the number of elements within a set.

Parameters

s – the set to query.

Returns

the number of elements in the set.

Broker::store_name
Type

function (h: opaque of Broker::Store) : string

Get the name of a store.

Returns

the name of the store.

Broker::table_clear
Type

function (t: Broker::Data) : bool

Remove all elements within a table.

Parameters

t – the table to clear.

Returns

always true.

Broker::table_contains
Type

function (t: Broker::Data, key: any) : bool

Check if a table contains a particular key.

Parameters
  • t – the table to query.

  • key – the key to check for existence.

Returns

true if the key exists in the table.

Broker::table_create
Type

function () : Broker::Data

Create communication data of type “table”.

Broker::table_insert
Type

function (t: Broker::Data, key: any, val: any) : Broker::Data

Insert a key-value pair into a table.

Parameters
  • t – the table to modify.

  • key – the key at which to insert the value.

  • val – the value to insert.

Returns

true if the key-value pair was inserted, or false if the key already existed in the table.

Broker::table_iterator
Type

function (t: Broker::Data) : opaque of Broker::TableIterator

Create an iterator for a table. Note that this makes a copy of the table internally to ensure the iterator is always valid.

Parameters

t – the table to iterate over.

Returns

an iterator.

Broker::table_iterator_last
Type

function (it: opaque of Broker::TableIterator) : bool

Check if there are no more elements to iterate over.

Parameters

it – an iterator.

Returns

true if there are no more elements to iterator over, i.e. the iterator is one-past-the-final-element.

Broker::table_iterator_next
Type

function (it: opaque of Broker::TableIterator) : bool

Advance an iterator.

Parameters

it – an iterator.

Returns

true if the iterator, after advancing, still references an element in the collection. False if the iterator, after advancing, is one-past-the-final-element.

Broker::table_iterator_value
Type

function (it: opaque of Broker::TableIterator) : Broker::TableItem

Retrieve the data at an iterator’s current position.

Parameters

it – an iterator.

Returns

element in the collection that the iterator currently references.

Broker::table_lookup
Type

function (t: Broker::Data, key: any) : Broker::Data

Retrieve a value from a table.

Parameters
  • t – the table to query.

  • key – the key to lookup.

Returns

the value associated with the key. If the key did not exist, then the optional field of the returned record is not set.

Broker::table_remove
Type

function (t: Broker::Data, key: any) : Broker::Data

Remove a key-value pair from a table.

Parameters
  • t – the table to modify.

  • key – the key to remove from the table.

Returns

the value associated with the key. If the key did not exist, then the optional field of the returned record is not set.

Broker::table_size
Type

function (t: Broker::Data) : count

Get the number of elements within a table.

Parameters

t – the table to query.

Returns

the number of elements in the table.

Broker::vector_clear
Type

function (v: Broker::Data) : bool

Remove all elements within a vector.

Parameters

v – the vector to clear.

Returns

always true.

Broker::vector_create
Type

function () : Broker::Data

Create communication data of type “vector”.

Broker::vector_insert
Type

function (v: Broker::Data, idx: count, d: any) : bool

Insert an element into a vector at a particular position, possibly displacing existing elements (insertion always grows the size of the vector by one).

Parameters
  • v – the vector to modify.

  • d – the element to insert.

  • idx – the index at which to insert the data. If it is greater than the current size of the vector, the element is inserted at the end.

Returns

always true.

Broker::vector_iterator
Type

function (v: Broker::Data) : opaque of Broker::VectorIterator

Create an iterator for a vector. Note that this makes a copy of the vector internally to ensure the iterator is always valid.

Parameters

v – the vector to iterate over.

Returns

an iterator.

Broker::vector_iterator_last
Type

function (it: opaque of Broker::VectorIterator) : bool

Check if there are no more elements to iterate over.

Parameters

it – an iterator.

Returns

true if there are no more elements to iterator over, i.e. the iterator is one-past-the-final-element.

Broker::vector_iterator_next
Type

function (it: opaque of Broker::VectorIterator) : bool

Advance an iterator.

Parameters

it – an iterator.

Returns

true if the iterator, after advancing, still references an element in the collection. False if the iterator, after advancing, is one-past-the-final-element.

Broker::vector_iterator_value
Type

function (it: opaque of Broker::VectorIterator) : Broker::Data

Retrieve the data at an iterator’s current position.

Parameters

it – an iterator.

Returns

element in the collection that the iterator currently references.

Broker::vector_lookup
Type

function (v: Broker::Data, idx: count) : Broker::Data

Lookup an element in a vector at a particular position.

Parameters
  • v – the vector to query.

  • idx – the index to lookup.

Returns

the value at the index. If the index was larger than any valid index, the optional field of the returned record is not set.

Broker::vector_remove
Type

function (v: Broker::Data, idx: count) : Broker::Data

Remove an element from a vector at a particular position.

Parameters
  • v – the vector to modify.

  • idx – the index to remove.

Returns

the value that was just evicted. If the index was larger than any valid index, the optional field of the returned record is not set.

Broker::vector_replace
Type

function (v: Broker::Data, idx: count, d: any) : Broker::Data

Replace an element in a vector at a particular position.

Parameters
  • v – the vector to modify.

  • d – the element to insert.

  • idx – the index to replace.

Returns

the value that was just evicted. If the index was larger than any valid index, the optional field of the returned record is not set.

Broker::vector_size
Type

function (v: Broker::Data) : count

Get the number of elements within a vector.

Parameters

v – the vector to query.

Returns

the number of elements in the vector.