4.2 Naming

All functions are named according to one of the following schemes:

• verb_noun
• verb_noun_with_noun
• noun_attribute
• set_noun_attribute
• noun_from_noun – convert from one type to another (avoid noun_to_noun)

The sole exceptions to this are where we have MuPDF specific functions that emulate (or extend) ‘well known’ functions, where we parrot those functions. For example ‘fz_printf’ or ‘fz_strdup’.

In addition, we avoid using ‘get’ in function names as this is generally redundant. In contrast, however, we do use ‘set’ where required. Consider for instance fz_aa_level (to retrieve the current anti-aliasing level), and fz_set_aa_level (to update it).

MuPDF makes extensive use of reference counting (see section 21.3 Reference Counting for more details). We reserve various words to indicate that reference counting is being used:

• Indicates that this call creates a new object and returns a reference to it. For example, fz_new_pixmap.
• Indicates that this call locates an object from somewhere (typically either from a cache, or from a set of standard objects), and returns a new reference to it. For example, fz_find_color_converter.
• Indicates that this call creates a new object and returns a reference to it. This is akin to ‘new’, but carries the implication that the operation will read some data and require some (possibly significant) amount of data processing before the object is created. For example, fz_load_outline or fz_load_jpeg.
• Indicates that this call will create a stream object, and return a reference to it. For example, fz_open_document.
• Indicates that this call will create a new reference to an existing referenced object. For example, fz_keep_colorspace.

All of these calls return an object reference. It is the callers responsibility to store this reference safely somewhere for the duration of the required lifespan of the object, and to destroy that reference when the caller no longer requires it.

No function should return ownership of a reference without being named with one of the reserved words above.

Once all the references to a given object are released, the system will remove the object itself.

• Indicates that this call will relinquish ownership of the object passed in. For example, fz_drop_font.

Failure to drop references will result in memory leaks. Dropping references too early may result in crashes due to objects being accessed after they have been destroyed.

API functions to destroy objects that are not subject to reference counted can be destroyed by calling functions using the words ‘drop’, ‘close’ or ‘free’.

In contrast to ‘find’ described above, we have one other reserved word regarding searching:

• Indicates that the call will return a borrowed pointer (or a value). For example, fz_lookup_pixmap_converter.

When we have a structure already allocated, and we wish to initialise some or all of its internal details, we use ‘init’. The matching pair to this should be named ’fin’. For example, fz_cmm_init_profile is matched by fz_cmm_fin_profile.

Some objects are created using functions using the verb ‘create’. Sometimes these can be reference counted objects (e.g. ‘pdf_create_document’), in which case they should be ‘drop’ped as usual. Non reference counted objects should be ‘destroyed’ (e.g. fz_destroy_mutex.