The heap memory manager is a thin wrapper around the traditional malloc() and free() routines. Having this layer provides two benefits:

• We can later use a different memory manager, such as the Boehm GC, without having to repeatedly change the existing code.
• We can prevent the duplication of repetitive code related to memory management, such as checking whether malloc() returns a valid pointer.

In order to avoid expensive copy operations on the heap, it becomes necessary to implement copy on write using reference counting. By creating a reference counted object model, we can have a hierarchy of abstract data types "deriving" from this base object model.

The fundamental idea behind this object model is that it encapsulates an ID, a reference count, and optionally a payload along with a v-table for the payload. The payload is a void pointer to the derived object data.

With this model in place, it becomes comparatively easy to also create generic data structures such as vectors and maps while benefitting from the performance gains introduced by copy on write.

We'll also explore in this issue the creation of semi-smart pointers to the object type using GCC's cleanup attribute.

String handling is an essential aspect, and in today's age it is important to have UTF-8 compatibility. I initially thought of writing the string interface from scratch, but eventually decided against that. Instead, I have settled on using the Simple Direct String Library (of Redis fame), and creating a thin wrapper around it for use with UTF-8 strings.

The runtime check macros are required to check pre-conditions and post-conditions. These checks are implemented through assert and require macros (inspired by Kotlin).

The assert macros check conditions that should never fail, whereas the require macros check for conditions that may fail. assert macros abort on failure, and require macros raise an exception. In general, but not always, pre-conditions are verified through assert macros, and post-conditions are validated through require macros.

As of now, we are not focusing on creating an exception handling mechanism, and allow both the assert and require macros to abort on failure.

We need the basic scaffolding to build the project. The scaffolding consists of the first version of the project Makefile along with the skeletal source code tree.

The table interface, along with the table type, is probably the most important data structure of Inquery. It represents a database table, and will be the type returned as results of database queries. The table interface builds on the inquery_record interface, and can be viewed logically as an array of records.

The table interface will be quite similar to that of the inquery_record type, and is expected to contain the following functions:

• inquery_table_new()
• inquery_table_copy()
• inquery_table_free()
• inquery_table_len()
• inquery_table_get()
• inquery_table_set()
• inquery_table_json()

The field type, proposed to be named as inquery_attribute, would represent an attribute of a given database model. In concrete terms, it would represent an individual field of a database record.

My initial idea is to have the inquery_attribute as a specialisation of inquery_object, with a payload containing the following fields:

• key
• value
• type
  The key would be a string, the value would be a void pointer, and the type would an enumeration.

The interface for this type would be something like this:

• inquery_attribute_new()
• inquery_attribute_copy()
• inquery_attribute_free()
• inquery_attribute_key()
• inquery_attribute_key_set()
• inquery_attribute_value()
• inquery_attribute_value_set()
• inquery_attribute_type()
• inquery_attribute_type_set()
• inquery_attribute_string()
• inquery_attribute_json()

Now that the attribute interface is ready, the next logical abstraction to create is a record, with is simply an array of related attributes. Since in practice the number of fields in a record remains constant throughout the duration of its existence, the record type will be space-immutable (but mutable as far as content is concerned). As usual, the record type will be a specialisation of the inquery_object type since we want the record type to be reference counted to take advantage of lazy copying.

Provisionally, the record interface will have the following interface:

• inquery_record_new()
• inquery_record_copy()
• inquery_record_free()
• inquery_record_get()
• inquery_record_set()
• inquery_record_len()
• inquery_record_json()

The province model is the first database model that I have planned out. Although provinces no longer exist in India, I am using the word to denote both states and union territories, since it makes sense to represent them as a single entity.

The province model will contain the following fields:

• id - integer primary key
• name - name of the province
• iso_code - the ISO code for the province
• is_ut - flag to indicate whether the province is a union territory

As for the interface, we would have the following functions:

• inquery_model_province_list()
• inquery_model_province_list_state()
• inquery_model_province_list_ut()
• inquery_model_province_single()
• inquery_model_province_single_name()
• inquery_model_province_single_iso()

Ideally, we also need an inquery_model_province_filter() function, but I need to think a bit more on how to implement it. Furthermore, the *_list() family of functions need to have a parameter specifying the ordering of the results, but I also need to think about how to abstract this.