The Monolith Dictionary

Overview

The monolith dictionary is an internal hashmap used to store and retrieve data. Usually this is used for pages, but it has been extended to be used for other data like ftables, and images.

This page aims to provide an overview of how this dictionary works under the hood, with links to the appropriate sections in the source code.

Main section on the dictionary can be found here: 11.3. Page Dictionary (included in top-level struct)

Pages Vs Entries

In Monolith, pages have a specific meaning and refer to a specific interface abstraction. Entriesrefer to the items that can be added to a dictionary.

At one point, pages were the only thing that could be added to dictionaries, as that was the original purpose for building the dictionary in the first place. For this reason there is a heavy emphasis on pages in the structure; Some older parts of the program may still refer to entries as pages.

Adding new entries to the dictionary

A new Monolith Page can be added to the dictionary with monolith_dict_newpage: 11.3.10. Page Entry Creation

Create a generic dictionary entry with monolith_dict_newentry. This was extracted from monolith_dict_newpage in a refactoring effort. 11.3.11. Generic Entry Creation

Dictionary Find and Lookup

Here we get into confusing terminology: findand lookup mean different things.

monolith_dict_find is used to retrieve generic entries from a dictionary given a keyword. 11.3.2. Entry Find.

The function monolith_dict_lookup is used specifically to find a monolith page: 11.3.1. Entry Page Lookup. This was the original way to retrieve data from a dictionary before generic entries were introduced.

Managing Data inside of an Entry

An entry is defined as a struct called monolith_dict_entry. Inside of this struct is a generic pointer called ud, where one can store data. 11.3.3. Entry Struct. The monolith page (11.4. Page Struct Declaration), for example, stores it's data using this ud value.

User Data in the entry is cleaned up when the list it belongs to gets freed via monolith_dict_entrylist_free: 11.3.4.3. Entry List Cleanup. At the moment, specific types are hard-coded to have different behaviors of freeing data. In the future, the hope is to have a more general purpose interface.