Functions
Creates a new instance of a hash table.
Creates a new instance of a hash table with a custom allocator.
Creates a new instance of a hash table with a suggested starting size.
Creates a new instance of a hash table with a custom allocator and a suggested starting size.
Special Memory Optimization: Allows you to create new LuaHashMaps from an existing one which will share the same lua_State under the hood.
Just like LuaHashMap_CreateShare, except it allows you to pre-size the hash map.
Special Memory Optimization: Allows you to create new LuaHashMaps from an existing lua_State.
Just like LuaHashMap_CreateShareFromLuaState but lets you specify your own allocator and pre-size hints.
Just like LuaHashMap_CreateShareFromLuaState but lets you specify your own pre-size hints.
Frees a LuaHashMap instance.
Frees a LuaHashMap instance (intended for those created with LuaHashMap_CreateShare or LuaHashMap_CreateShareFromLuaState).
Detailed Description
Function Documentation
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.
// (do stuff as you normally do to use each hash map)
// When done, free resources.
// Make sure that LuaHashMap_Free is called last, after all the shares are closed.
- 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
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
)
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_FreeShare
(
LuaHashMap *
hash_map )