Functions
LuaHashMap *	LuaHashMap_Create (void)
	Creates a new instance of a hash table.

LuaHashMap *	LuaHashMap_CreateWithAllocator (lua_Alloc the_allocator, void *user_data)
	Creates a new instance of a hash table with a custom allocator.

LuaHashMap *	LuaHashMap_CreateWithSizeHints (int number_of_array_elements, int number_of_hash_elements)
	Creates a new instance of a hash table with a suggested starting size.

LuaHashMap *	LuaHashMap_CreateWithAllocatorAndSizeHints (lua_Alloc the_allocator, void *user_data, int number_of_array_elements, int number_of_hash_elements)
	Creates a new instance of a hash table with a custom allocator and a suggested starting size.

LuaHashMap *	LuaHashMap_CreateShare (LuaHashMap *original_hash_map)
	Special Memory Optimization: Allows you to create new LuaHashMaps from an existing one which will share the same lua_State under the hood.

LuaHashMap *	LuaHashMap_CreateShareWithSizeHints (LuaHashMap *original_hash_map, int number_of_array_elements, int number_of_hash_elements)
	Just like LuaHashMap_CreateShare, except it allows you to pre-size the hash map.

LuaHashMap *	LuaHashMap_CreateShareFromLuaState (lua_State *lua_state)
	Special Memory Optimization: Allows you to create new LuaHashMaps from an existing lua_State.

LuaHashMap *	LuaHashMap_CreateShareFromLuaStateWithAllocatorAndSizeHints (lua_State lua_state, lua_Alloc the_allocator, void user_data, int number_of_array_elements, int number_of_hash_elements)
	Just like LuaHashMap_CreateShareFromLuaState but lets you specify your own allocator and pre-size hints.

LuaHashMap *	LuaHashMap_CreateShareFromLuaStateWithSizeHints (lua_State *lua_state, int number_of_array_elements, int number_of_hash_elements)
	Just like LuaHashMap_CreateShareFromLuaState but lets you specify your own pre-size hints.

void	LuaHashMap_Free (LuaHashMap *hash_map)
	Frees a LuaHashMap instance.

void	LuaHashMap_FreeShare (LuaHashMap *hash_map)
	Frees a LuaHashMap instance (intended for those created with LuaHashMap_CreateShare or LuaHashMap_CreateShareFromLuaState).

Detailed Description

Function Documentation

LuaHashMap* LuaHashMap_Create ( void )

Creates a new instance of a hash table.

This creates a new instance of a LuaHashMap. You will use this as your opaque LuaHashMap "object" for all the per-instance hash map operations.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

See Also: LuaHashMap_Free, LuaHashMap_CreateWithAllocator, LuaHashMap_CreateWithSizeHints, LuaHashMap_CreateWithAllocatorAndSizeHints, LuaHashMap_CreateShare, LuaHashMap_CreateShareWithSizeHints, LuaHashMap_CreateShareFromLuaState, uaHashMap_CreateShareFromLuaStateWithAllocatorAndSizeHints, LuaHashMap_CreateShareFromLuaStateWithSizeHints

LuaHashMap* LuaHashMap_CreateShare ( LuaHashMap * original_hash_map )

Special Memory Optimization: Allows you to create new LuaHashMaps from an existing one which will share the same lua_State under the hood.

Currently, every LuaHashMap instance created with the Create family of functions (excluding CreateShare) will create a brand new virtual machine (lua_State*). My measurements of a new lua_State instance seem to take about 4-5KB on 64-bit Mac. This function was designed to let you avoid incuring that cost by letting you reuse another LuaHashMap's lua_State. But for all other purposes (besides freeing), your hash map instances will appear completely independent and the API calls you make don't change in any other way.

LuaHashMap* first_hash_map = LuaHashMap_Create();
LuaHashMap* second_hash_map = LuaHashMap_CreateShare(first_hash_map);
LuaHashMap* third_hash_map = LuaHashMap_CreateShare(second_hash_map);
LuaHashMap* fourth_hash_map = LuaHashMap_CreateShare(first_hash_map);
// (do stuff as you normally do to use each hash map)
// When done, free resources.
LuaHashMap_FreeShare(fourth_hash_map);
LuaHashMap_FreeShare(second_hash_map);
LuaHashMap_FreeShare(third_hash_map);
// Make sure that LuaHashMap_Free is called last, after all the shares are closed.
LuaHashMap_Free(first_hash_map);

Parameters

original_hash_map The hash map you want to reuse a lua_State from.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

Note: Technically speaking, the original and shared maps are peers of each other. The implementation does not make a distinction about which one the original is so any hash map with the lua_State you want to share may be passed in as the parameter. Make sure to free any shared maps with FreeShare() before you close the final hash map with Free() as Free() calls lua_close() which destroys the lua_State.

See Also: LuaHashMap_FreeShare, LuaHashMap_Free, LuaHashMap_CreateShareWithSizeHints, LuaHashMap_CreateShareFromLuaState, LuaHashMap_CreateShareFromLuaStateWithAllocatorAndSizeHints, LuaHashMap_CreateShareFromLuaStateWithSizeHints, LuaHashMap_CreateShareFromLuaState.

LuaHashMap* LuaHashMap_CreateShareFromLuaState ( lua_State * lua_state )

Special Memory Optimization: Allows you to create new LuaHashMaps from an existing lua_State.

This will create a new LuaHashMap instance from a pre-existing lua_State with the intention of saving memory. Currently, every LuaHashMap instance created with the Create family of functions (excluding CreateShare) will create a brand new virtual machine (lua_State*). My measurements of a new lua_State instance seem to take about 4-5KB on 64-bit Mac. This function was designed to let you avoid incuring that cost by letting you reuse a lua_State that you may already have for other purposes. But for all other purposes (besides freeing), your hash map instances will appear completely independent and the API calls you make don't change in any other way. LuaHashMap uses the Lua registry with luaL_ref/luaL_unref (to get a unique table), so it should not collide or intefere with anything you are doing in your Lua state.

Parameters

lua_state A lua_State you wish to use/share with your hash map

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

Note: Use LuaHashMap_FreeShare to free the hash_map when you are done. You must do this before you close your lua_State.

Warning: This is for very advanced use cases that want to directly interact with the Lua State. An understanding of the implementation details of LuaHashMap is strongly recommended in order to avoid trampling over each other.

See Also: LuaHashMap_FreeShare, LuaHashMap_Free, LuaHashMap_CreateShare, LuaHashMap_CreateWithSizeHints, LuaHashMap_CreateShareFromLuaState

LuaHashMap* LuaHashMap_CreateShareFromLuaStateWithAllocatorAndSizeHints	(	lua_State *	lua_state,
		lua_Alloc	the_allocator,
		void *	user_data,
		int	number_of_array_elements,
		int	number_of_hash_elements
	)

Just like LuaHashMap_CreateShareFromLuaState but lets you specify your own allocator and pre-size hints.

Parameters

lua_state	A lua_State you wish to use/share with your hash map
the_allocator	The custom memory allocator you want to provide.
user_data	A user data/context pointer to go with the allocator.*
number_of_array_elements	Lua tables double as both arrays and hash tables in Lua. As such, this parameter let's you pre-size the number of array elements. Most users of this library will probably use 0 because they don't need the array part.
number_of_hash_elements	This parameter is used to pre-size the number of hash buckets.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

Note: Use LuaHashMap_FreeShare to free the hash_map when you are done. You must do this before you close your lua_State.

Warning: This is for very advanced use cases that want to directly interact with the Lua State. An understanding of the implementation details of LuaHashMap is strongly recommended in order to avoid trampling over each other.

See Also: LuaHashMap_FreeShare, LuaHashMap_Free, LuaHashMap_CreateShare, LuaHashMap_CreateWithAllocatorAndSizeHints, LuaHashMap_CreateShareFromLuaState

LuaHashMap* LuaHashMap_CreateShareFromLuaStateWithSizeHints	(	lua_State *	lua_state,
		int	number_of_array_elements,
		int	number_of_hash_elements
	)

Just like LuaHashMap_CreateShareFromLuaState but lets you specify your own pre-size hints.

Parameters

lua_state	A lua_State you wish to use/share with your hash map
number_of_array_elements	Lua tables double as both arrays and hash tables in Lua. As such, this parameter let's you pre-size the number of array elements. Most users of this library will probably use 0 because they don't need the array part.
number_of_hash_elements	This parameter is used to pre-size the number of hash buckets.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

Note: Use LuaHashMap_FreeShare to free the hash_map when you are done. You must do this before you close your lua_State.

Warning: This is for very advanced use cases that want to directly interact with the Lua State. An understanding of the implementation details of LuaHashMap is strongly recommended in order to avoid trampling over each other.

See Also: LuaHashMap_FreeShare, LuaHashMap_Free, LuaHashMap_CreateShare, LuaHashMap_CreateWithAllocatorAndSizeHints, LuaHashMap_CreateShareFromLuaState

LuaHashMap* LuaHashMap_CreateShareWithSizeHints	(	LuaHashMap *	original_hash_map,
		int	number_of_array_elements,
		int	number_of_hash_elements
	)

Just like LuaHashMap_CreateShare, except it allows you to pre-size the hash map.

Parameters

original_hash_map	The hash map you want to reuse a lua_State from.
number_of_array_elements	Lua tables double as both arrays and hash tables in Lua. As such, this parameter let's you pre-size the number of array elements. Most users of this library will probably use 0 because they don't need the array part.
number_of_hash_elements	This parameter is used to pre-size the number of hash buckets.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

See Also: LuaHashMap_FreeShare, LuaHashMap_Free, LuaHashMap_CreateShare, LuaHashMap_CreateWithSizeHints, LuaHashMap_CreateShareFromLuaState

LuaHashMap* LuaHashMap_CreateWithAllocator	(	lua_Alloc	the_allocator,
		void *	user_data
	)

Creates a new instance of a hash table with a custom allocator.

This creates a new instance of a LuaHashMap with a custom allocator. The allocator adopts the lua_Alloc model as defined by Lua.

You will use this as your opaque LuaHashMap "object" for all the per-instance hash map operations.

Parameters

the_allocator	The custom memory allocator you want to provide.
user_data	A user data/context pointer to go with the allocator.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

See Also: LuaHashMap_Free, LuaHashMap_Create, LuaHashMap_CreateWithSizeHints, LuaHashMap_CreateWithAllocatorAndSizeHints, LuaHashMap_CreateShare, LuaHashMap_CreateShareWithSizeHints

LuaHashMap* LuaHashMap_CreateWithAllocatorAndSizeHints	(	lua_Alloc	the_allocator,
		void *	user_data,
		int	number_of_array_elements,
		int	number_of_hash_elements
	)

Creates a new instance of a hash table with a custom allocator and a suggested starting size.

This creates a new instance of a LuaHashMap with a custom allocator. The allocator adopts the lua_Alloc model as defined by Lua. This also let's you hint Lua on how many elements to pre-size the hash table for. If you know the size your hash is going to grow to, this you should specify this number as a performance optimization. Growing the hash table after running out of buckets is generally an expensive operation so pre-sizing it can help.

You will use this as your opaque LuaHashMap "object" for all the per-instance hash map operations.

Parameters

the_allocator	The custom memory allocator you want to provide.
user_data	A user data/context pointer to go with the allocator.*
number_of_array_elements	Lua tables double as both arrays and hash tables in Lua. As such, this parameter let's you pre-size the number of array elements. Most users of this library will probably use 0 because they don't need the array part.
number_of_hash_elements	This parameter is used to pre-size the number of hash buckets.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

See Also: LuaHashMap_Free, LuaHashMap_Create, LuaHashMap_CreateWithAllocator, LuaHashMap_CreateWithSizeHints, LuaHashMap_CreateShare, LuaHashMap_CreateShareWithSizeHints

LuaHashMap* LuaHashMap_CreateWithSizeHints	(	int	number_of_array_elements,
		int	number_of_hash_elements
	)

Creates a new instance of a hash table with a suggested starting size.

This creates a new instance of a LuaHashMap with a hint to Lua on how many elements to pre-size the hash table for. If you know the size your hash is going to grow to, this you should specify this number as a performance optimization. Growing the hash table after running out of buckets is generally an expensive operation so pre-sizing it can help.

You will use this as your opaque LuaHashMap "object" for all the per-instance hash map operations.

Parameters

number_of_array_elements	Lua tables double as both arrays and hash tables in Lua. As such, this parameter let's you pre-size the number of array elements. Most users of this library will probably use 0 because they don't need the array part.
number_of_hash_elements	This parameter is used to pre-size the number of hash buckets.

Returns: Returns a pointer to the LuaHashMap instance created or NULL if a failure.

Note: Read the Lua Gems free chapter for more information about how Lua tables work.

See Also: LuaHashMap_Free, LuaHashMap_Create, LuaHashMap_CreateWithAllocator, LuaHashMap_CreateWithAllocatorAndSizeHints, LuaHashMap_CreateShare, LuaHashMap_CreateShareWithSizeHints

void LuaHashMap_Free ( LuaHashMap * hash_map )

Frees a LuaHashMap instance.

This releases the memory associated with the LuaHashMap.

Parameters

hash_map The LuaHashMap instance to operate on.

Note: This closes the lua_State. If there are any shared hash maps (used LuaHashMap_CreateShare), the shared hash maps must be freed before this is called.

See Also: LuaHashMap_FreeShare, LuaHashMap_Create, LuaHashMap_CreateShare, LuaHashMap_CreateShareFromLuaState

void LuaHashMap_FreeShare ( LuaHashMap * hash_map )

Frees a LuaHashMap instance (intended for those created with LuaHashMap_CreateShare or LuaHashMap_CreateShareFromLuaState).

This releases the memory associated with the LuaHashMap that were created with LuaHashMap_CreateShare or LuaHashMap_CreateShareFromLuaState.

Parameters

hash_map The LuaHashMap instance to operate on.

Note: This cleans up everything in the LuaHashMap instance, but avoids a call to lua_close() which would otherwise destroy the lua_State and break any other thing sharing that lua_State.

See Also: LuaHashMap_FreeShare, LuaHashMap_Create, LuaHashMap_CreateShare, LuaHashMap_CreateShareFromLuaState, LuaHashMap_CreateShareWithSizeHints, LuaHashMap_CreateShareFromLuaState, LuaHashMap_CreateShareFromLuaStateWithAllocatorAndSizeHints, LuaHashMap_CreateShareFromLuaStateWithSizeHints

Functions

Detailed Description

Function Documentation