New hash

19.0.0 released Nov 08, 2023

New hash

Purpose: Create hash table.

new-hash [ define ] <hash> size <size> [ process-scope ]

new-hash initializes hash table named <hash>, which is a pointer to type "vely_hash" and can be created with optional "define". <size> is the number of "buckets" in the hash table. All elements with the same hash code are stored in a linked list within the same bucket. Greater table size usually means less elements per bucket and better performance. However, memory usage grows with a bigger hash table, so its size should be balanced based on the program needs.

Vely uses high-performing FNV1_a hash algorithm. Each element in a bucket list is lightweight, containing pointers to a key, value and next element in the linked list.

<size> must be at least 10; if less, it will be set to 10.

Allocated internals

<hash> is allocated memory along with additional internal memory, which can be released if purge-hash is used with <hash> from a previously executed new-hash.

Scope

Note that a hash table is accessible to the current process only, unless "process-scope" clause is used, in which case all requests served by the process can use it (see do-once for a typical way to create hash with a process scope). If "process-scope" is used, then optional "define" will create <hash> that is static, meaning it will keep its value between requests (or in general between different invocations). If you do not use "define", then <hash> must be declared as a global or static variable.

If "process-scope" is used, then keys and data writen to <hash> must be allocated memory produced by another Vely statement, or they must be some other kind of global variables (such as constants, static variables, global C variables, unmanaged heap memory etc.). See write-hash for an example of a process-scoped tree.

Examples

Create a new hash with 500 buckets:

new-hash define h size 500

See read-hash for more examples.