Conventions

This page documents various conventions within pntOS. Types documents conventions which limit the ways pntOS uses a type so the user can understand what it represents without any additional information. Inheritance describes the conventions pntOS uses to implement inheritance as a pattern in C.

Types

For clarity and ease-of-use, pntOS uses the following conventions in its API:

• char* is a C-string, meaning that it is terminated by a NULL character, which can be used to determine its length.

• unsigned char* is not a C-string. NULL characters can exist throughout the array. Instead, a separate length field exists to provide the length of the array. This type indicates an opaque data stream.

• Foo** (a pointer to a pointer to the arbitrary type Foo) represents an array of pointers to Foo. The one exception to this rule is char**, which instead represents an array of null-terminated C-strings. In all cases a separate length field exists to provide the length of the array.

• void* denotes an unknown type that needs to be decoded first before anything is done with it. “decoded” simply means to cast to the known type. For example, see the receiver parameter in the callback function pointer in PntosKeyValueStore::request_notify.

Inheritance

pntOS implements an inheritance scheme via the following conventions:

• Usually, the base class name will start with the name PntosCommmon (e.g. PntosCommonInertial).

• Every polymorphic base class contains an enum field (e.g. PntosCommonInertial::inertial_type). The value of this enum field indicates which child class the base object can be downcast to. The child class name will always be the PascalCase equivalent of the UPPER_SNAKE_CASE enum value. For example, if the PntosCommonInertial::inertial_type field is equal to PntosInertialType::PNTOS_STANDARD_INERTIAL_MECHANIZATION then the object can be cast to PntosStandardInertialMechanization.

• Every child class will have the base class object as its first field (e.g. PntosStandardInertialMechanization::common).

Note

This inheritance pattern is made possible because the C standard states:

A pointer to a structure object, suitably cast, points to its initial member