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><vendor>_<library>_<subject>_<verb>_<object>_<modifiers>

Prefix

Prefix	Description
	[no prefix] A (usually global) function that must check its parameters and must not crash if any parameters are NULL
_	A (usually global) function that MUST NOT check its parameters
__	A function, that is an implementation detail but need not be static

Vendor

It's "mulle". Must not contain undescores. Static functions may omit the vendor namespacing scope. Especially if the chances are slim, that the function will ever be lifted to global scope.

Library

The library or package the function belongs to. Must not contain underscores. Since "objc-runtime" is even too long for me, it's been shortened to a "package" name objc. A package is a collection of libraries, such as mulle-objc or MulleFoundation. Statoc function may omit this also.

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
environment	Function operates on the environment
	No subject indicates that the function operates on the currently applicable universe

Verb (+ technical modifiers)

The verb is a concatenation of technical modifiers with the actual verb without underscores. The verb itself preferably has no underscores.

Modifiers	Description
inline	Inline function, used when neccesarry to distinguish from a non-inline function of otherwiese the same name
partialinline	Used when its neccessary to distinguish from another inline function
atomic	Atomic function, if there is noatomic function available, or if the verb doesn't imply atomicity.

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.

The object preferably has no underscores.

Semantic 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 must 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