How to name a mulle objc runtime function

The mulle-objc-runtime is also an ongoing experiment in C function naming. The function names of the runtime have been in constant refinement.

The C function name should

• have its own namespace
• give as much information as possible about its function
• should be uniform in structure
• ideally it should be simple to compose a function name, without having to think too much about it (i.e. algorithmically)

The general form is:

<prefix>_<subject>_<verb>_<object>_<modifiers>

Prefix

Prefix	Description
mulle_objc	A (usually global) function that must check its parameters and must not crash if any parameters are NULL
_mulle_objc	A (usually global) function that MUST NOT check its parameters
__mulle_objc	A private function, that is an implementation detail

Static functions may omit the mulle_objc namespacing scope, if the chances are slim, that it will ever be lifted to global scope.

Subject

The subject is the type of the first parameter of the function without namespace. I.e. dosomething( struct _bar *p) should be written as bar_dosomething( struct _bar *p).

There can be implicit subjects and here is a list:

Implicit Subject	Description
thread	Function operates on a thread variable
global	Function operates on a global variable
	No subject indicates that the function operates on the currently applicable universe

Verb

The verb is a concatenation of technical modifiers with the actual verb without underscores.

Modifiers	Description
inline	Inline function
partialinline	Used when its neccessary to distinguish from another inline function

The verb list is taken from mulle-container

Object

An object is typically a property of the object, lets say a variable of the structure. So an inline function that only does return( bar->x) would be written as

static inline int  _mulle_objc_bar_inlineget_x( struct _bar *bar)
{
   return( bar->x);
}

The prefix _mulle_objc is chosen, as there is no NULL check and the function can potentially crash. This is followed by the subject "bar" which is the first parameter of the function and the structure being operated upon (put this always as the first parameter). The function is inline so we need the technical modififier on get. Finally 'x' is returned so that is the object.

Modifiers

Variations of the same functions exist. Also it is convenient to expose any nonstandard error handling in name not just in type. Therefore the functionname maybe adorned with a number of modifiers. The modifier should not contain an underscore. Modifiers are concatenated with underscore. The concatentaion should be in ASCII sort order.

A negative modifier should be no<modifier> an exclusive modifier should be <only>modifier

Modifier | Description ––––––––--–---–––|------------------------- nofail | The function will always return a valid value, otherwise an exception will be raised. nocache | The function does not touch the cache onlycache | The cache is exlusively used nocacheupdate | The cache will not be updated noforward | The forward method will be ignored / not checked