Handling keys

As discussed above, the Store is basically a set of key/value pairs. While the values are always fz_storables, the keys can be of many different types, due to coming from many disparate parts of the system.

Accordingly, we need a mechanism to allow us to safely know what `type' a given key is, and to compare 2 keys of identical type.

We solve this, by using a fz_store_type structure:

$\begin{lstlisting} typedef struct fz_store_type_s { int (*make_hash_key)(fz_con... ...; int (*needs_reap)(fz_context *ctx, void *); } fz_store_type; \end{lstlisting}$

We will have just one instance of this for each type - normally a static const structure defined in the code. Whenever we insert (or lookup) something in the store, we pass the address of that `types' structure.

We only compare items if they have the same type pointer, and any comparison is done using the cmp_key function pointer therein. In common with normal C idioms, 0 means match, non zero means different.

The keep_key and drop_key entries are used to implement reference counting of keys. Keys can be an amalgam of several reference counted objects, so a single call to the keep or drop functions provided here will take or release references for all these objects in one operation.

The print function is purely for debugging purposes as part of calls to fz_print_store - it should generate a human readable summary of the key to the given fz_output stream.

The make_hash_key and needs_reap functions are explained in the following subsections.