Home

Michael Heilmann's Arcadia Ring 1

This is the documentation for Michael Heilmann's Arcadia Ring 1. Arcadia Ring 1 facilitates the creation of C programs - in particular interpreters - that are portable, maintainable, as well as safe.

1. Files

You can find the sources of Arcadia Ring1 in my GitHub repository https://github.com/michaelheilmann/michaelheilmann.com. The subdirectory of Arcadia.Ring1 in the repository is here https://github.com/michaelheilmann/michaelheilmann.com/tree/main/repository/Arcadia.Ring1.

Arcadia Ring1 supports various platforms (including but not restricted to Windows, Linux, and many more), however, we currently only officially support Windows. Find instructions on how to build, test, and use Arcadia Ring1 under various systems, please refer to README.md in the root folder of the repository.

2. Further References

Arcadia Ring 1 relies on ARMS1.

3. Documentation

3.1.1. Boolean Type

Arcadia Ring 1 provides a boolean type.

typedef implementation detail Arcadia_BooleanValue

#define Arcadia_BooleanValue_True implementation detail

is a value of the type denoting logically true. It converts to 1 in arithmetic expressions.

#define Arcadia_BooleanValue_False implementation detail

is a value of the type denoting logically false. It converts to 0 in arithmetic expressions.

3.1.2. Foreign Procedure Type

Arcadia Ring 1 provides the Arcadia_ForeignProcedureValue type.

typedef implementation detail Arcadia_ForeignProcedureValue;

which is a pointer to a function adhering to the calling conventions for C functions of the runtime.

A valid value of the Arcadia_ForeignProcedureValue is the null value

#define Arcadia_ForeignProcedureValue_Null implementation detail

#define Arcadia_ForeignProcedureValue_NumberOfBits implementation detail

denotes the number of Bits of the type.

#define Arcadia_ForeignProcedureValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_ForeignProcedureValue_NumberOfBits divided by 8.

3.1.3. Integer Types

Arcadia Ring 1 provides a two's complement integer number types.

typedef implementation detail Arcadia_IntegerSuffixValue

where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The macros in this section all include the Suffix metavariable and are defined for the values 8, 16, 32, and 64 of that meta variable.

#define Arcadia_IntegerSuffixValue_NumberOfBits implementation detail

denotes the number of Bits of the type. The value is always equal to the value of the respective Suffix.

#define Arcadia_IntegerSuffixValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_IntegerSuffixValue_NumberOfBits divided by 8.

#define Arcadia_IntegerSuffixValue_Minimum implementation detail

denotes the least value (in terms of its magnitude) representable by a the Arcadia_IntegerSuffixValue type. The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 -128
16 -32768
32 -2147483648
64 -9223372036854775808

#define Arcadia_IntegerSuffixValue_Maximum implementation detail

denotes the greatest value (in terms of its magnitude) representable by a the Arcadia_IntegerSuffixValue type. The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 127
16 32767
32 2147483647
64 9223372036854775807

#define Arcadia_IntegerSuffixValue_Literal(x) implementation detail

is used to write a literal of the type Arcadia_IntegerSuffix in C source code. The following table denotes the expansions of the macro:

SuffixValue
8 x
16 x
32 x
64 x##LL

3.1.4. Natural Types

Arcadia Ring 1 provides natural number types.

typedef implementation detail Arcadia_NaturalSuffixValue

where Suffix denotes the number of Bits of the integer and can be one of 8, 16, 32, or 64.

The macros in this section all include the Suffix metavariable and are defined for the values 8, 16, 32, and 64 of that meta variable.

#define Arcadia_NaturalSuffixValue_NumberOfBits implementation detail

denotes the number of Bits of the type. The value is always equal to the value of the respective Suffix.

#define Arcadia_IntegerSuffixValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_IntegerSuffixValue_NumberOfBits divided by 8.

#define Arcadia_NaturalSuffixValue_Minimum implementation detail

denotes the least value (in terms of its magnitude) representable by a the Arcadia_NaturalSuffixValue type. The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 0
16 0
32 0
64 0

#define Arcadia_NaturalSuffixValue_Maximum implementation detail

denotes the greatest value (in terms of its magnitude) representable by a the Arcadia_NaturalSuffixValue type. The following table denotes the value of the constant for the respective Suffix

ConstantValue
8 255
16 65535
32 4294967295
64 18446744073709551615

#define Arcadia_NatualSuffixValue_Literal(x) implementation detail

is used to write a literal of the type Arcadia_NaturalSuffix in C source code. The following table denotes the expansions of the macro:

SuffixValue
8 x
16 x
32 x##U
64 x##ULL

3.1.5. Object Reference Type

R provides a ObjectReference type.

typedef implementation detail Arcadia_ObjectReferenceValue

The Arcadia_ObjectReferenceValue type is a pointer.

A valid value of the Arcadia_ObjectReferenceValue is the null reference

#define Arcadia_ObjectReferenceValue_Null implementation detail

#define Arcadia_ObjectReferenceValue_NumberOfBits implementation detail

denotes the number of Bits of the type.

#define Arcadia_ObjectReferenceValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_ObjectReferenceValue_NumberOfBits divided by 8.

3.1.6. Size Type

R provides an alias for builtin size_t type.

typedef implementation detail Arcadia_SizeValue

#define Arcadia_SizeValue_NumberOfBits implementation detail

denotes the number of Bits of the type. This number must one of 32 or 64, otherwise the environment is not supported by R. This restriction may be relaxed in future versions of R.

#define Arcadia_SizeValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_SizeValue_NumberOfBits divided by 8.

#define Arcadia_SizeValue_Minimum implementation detail

denotes the least value (in terms of its magnitude) representable by a the Arcadia_Size type.

#define Arcadia_SizeValue_Literal(x) implementation detail

is used to write a literal of type Arcadia_SizeValue in C source code.

3.1.7. Void Type

R provides a void type.

typedef implementation detail Arcadia_VoidValue

The only value of this type is Arcadia_VoidValue_Void. Arcadia_VoidValue is an unsigned integral type.

#define Arcadia_VoidValue_Void implementation detail

The single value of the type.

#define Arcadia_VoidValue_NumberOfBits implementation detail

denotes the number of Bits of the type.

#define Arcadia_VoidValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_VoidValue_NumberOfBits divided by 8.

3.2. Value Type

Arcadia_Value is a tagged union of values supported by the runtime. It consists of a tag indicating the value stored in the union and the union of the values. The following table lists all possible tags and their corresponding type.

Tag Type
Arcadia_ValueTag_Boolean Arcadia_BooleanValue
Arcadia_ValueTag_Integer16 Arcadia_Integer16Value
Arcadia_ValueTag_Integer32 Arcadia_Integer32Value
Arcadia_ValueTag_Integer64 Arcadia_Integer64Value
Arcadia_ValueTag_Integer8 Arcadia_Integer8Value
Arcadia_ValueTag_Natural16 Arcadia_Natural16Value
Arcadia_ValueTag_Natural32 Arcadia_Natural32Value
Arcadia_ValueTag_Natural64 Arcadia_Natural64Value
Arcadia_ValueTag_Natural8 Arcadia_Natural8Value
Arcadia_ValueTag_ObjectReferenceArcadia_ObjectReferenceValue
Arcadia_ValueTag_Size Arcadia_SizeValue
Arcadia_ValueTag_Void Arcadia_VoidValue

For each type, Arcadia_Value has three functions associated:

Type Arcadia_Value_getSuffix(Arcadia_Value const* value)
bool Arcadia_Value_isSuffix(Arcadia_Value const* value)
void Arcadia_Value_setSuffix(Arcadia_Value* value, Arcadia_SuffixValue VariableValue)

The following table lists the valid combinations of Suffix and Variable

Boolean boolean
Integer16 integer16
Integer32 integer32
Integer64 integer64
Integer8 integer8
Natural16 natural16
Natural32 natural32
Natural64 natural64
Natural8 natural8
ObjectReferenceobjectReference
Size size
Void void

Arcadia_Value_isSuffix returns true if the Arcadia_Value stores a value of the type corresponding to Suffix. Otherwise it returns false.

Arcadia_Value_setSuffix assigns the Arcadia_Value a value of the type corresponding to Suffix.

Arcadia_Value_getType get the value stored in the Arcadia_Value. The behavior of Arcadia_Value_setSuffix is undefined if the value does not store a value of the type corresponding to Suffix.

3.3. Status Codes

R provides a status type and symbolic constants for its values. That type denotes success or failure of program (or a part of it) as well as information on the reason for the failure.

typedef implementation detail Arcadia_Status

Arcadia_Status is a natural number type of a width of 32 Bit.

#definer Arcadia_Status_Success implementation detail

is the symbolic constant of the type Arcadia_Status has the value ((Arcadia_Status)0). It denotes success and is guaranteed to be defined to the value 0 of the underlaying natural number type of Arcadia_Status as well as to be the only symbolic constant starting with Arcadia_Status_ having defined to that value.

Symbolic constants of the form

#definer Arcadia_Status_Name implementation detail

where Name is not Success provide information on failure of a program (or a part of it). The following table denotes the value of the constant for the respective Name

Name Value
AllocationFailed An allocation failed.
ArgumentTypeInvalid The type of an argument is invalid.
ArgumentValueInvalid The value of an argument is invalid.
ConversionFailed A conversion failed.
DivisionByZero An divions by zero was detected.
EncodingInvalid An encoding is invalid.
Exists Something exists (but should not).
FileSystemOperationFailedA file system operation failed.
Initialized Something was initialized (but should not have been initialized).
NotExists Something does not exist.
NumberOfArgumentsInvalid The number of arguments is invalid.
OperationInvalid An operation is invalid.
SemanticalError
SyntacticalError
TestFailed A test failed. This is used by the built-in tests that ensure correctness.
TypeExists A type exists (but should not).
TypeNotExists A type does not exist (but should).
Uninitialized Something was uninitialized (but should have been initialized).

3.4. Status Variable

R provides a global status variable.

R_Status R_getStatus ( );

gets the value of the status variable. The initial value of the status variable is Arcadia_Status_Success.

void Arcadia_Process_setStatus ( Arcadia_Process* process, Arcadia_Status status );

sets the value of the status variable to the value status.

3.5. Jumps and Jump Targets

R provides non-local jumps by allowing to save and restore the C program state.

typedef implementation detail Arcadia_JumpTarget;

is a type of which its values are stack allocated.

void Arcadia_pushJumpTarget(Arcadia_JumpTarget* jumpTarget);

Push a jump target on top of the jump target stack. Initially, the jump target stack is empty.

void Arcadia_popJumpTarget();

Pop the jump target on top of the jump target stack. The jump target stack must not be empty.

void Arcadia_jump();

Jump to the jump target on top of the jump target stack. The jump target stack must not be empty.

#define Arcadia_JumpTarget_save(jumpTarget) implementation detail

Macro to save the current C program state into a jump target.

The canonical way of using Arcadia_pushJumpTarget, Arcadia_popJumpTarget, and Arcadia_jump is the following.

Arcadia_pushJumpTarget(&jumpTarget);
if (Arcadia_JumpTarget_save(&jumpTarget)) {
 (1)
 Arcadia_popJumpTarget();(2)
} else {
 Arcadia_popJumpTarget();(3)
 (4)
}
(5)

The if-branch is always entered at first as the Arcadia_JumpTarget_save() at its first invocation returns logically true. If the program at (1) does not jump to the jump target (using Arcadia_jump()), then Arcadia_popJumpTarget(); (2) and (5) are executed. If the program at (1) jumps to the jump target, then Arcadia_JumpTarget_save() is re-evaluated and returns logically false and Arcadia_popJumpTarget();(2) and (4) is executed.

One usage example is the implementation of the Arcadia_safeExecute function.

void Arcadia_safeExecute(void (*f)()) {
 Arcadia_JumpTarget jumpTarget;
 Arcadia_pushJumpTarget(&jumpTarget);
 if (Arcadia_JumpTarget_save(&jumpTarget)) {
  f();
  Arcadia_popJumpTarget();
 }
}

3.6. Numeric functions

Arcadia_clamp

Clamp a value to a range.

Type Arcadia_clampSuffix(Type value, Type lower, Type upper)

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue
Parameters
Type valueThe value to clamp.
Type lowerThe lower bound (inclusive).
Type upperThe upper bound (inclusive).

This function returns the value value clamped to the range [lower, upper].

Errors
Arcadia_Status_ArgumentValueInvalidlower > upper
Arcadia_Status_EncodingInvalid The sequence of Bytes does not represented a UTF-8-NO-BOM string.
Return value

The value value clamped to the range [lower, upper].

Arcadia_countLeadingZeroes

Return the number of leadin gzeroes of the binary representation of a value.

Arcadia_SizeValue Arcadia_countLeadingZeroesSuffix(Type value)

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function returns the number of leading zeroes of the binary representation of value.

Return value

The number of leading zeroes.

Arcadia_hash

Return the hash of a value.

Arcadia_SizeValue Arcadia_hashSuffix(Type x)

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
BooleanValue Arcadia_BooleanValue
ForeignProcedureValueArcadia_ForeignProcedureValue
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value
SizeValue Arcadia_SizeValue
VoidValue Arcadia_VoidValue
Parameters
Type xThe value.
Return value

Return hash of x.

Arcadia_maximum

Return the maximum of two values.

Type Arcadia_maximumSuffix(Type x, Typemv> y)

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Integer8ValueArcadia_Integer8Value
Integer16ValueArcadia_Integer16Value
Integer32ValueArcadia_Integer32Value
Integer64ValueArcadia_Integer64Value
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue
Parameters
Type xThe first value.
Type yThe second value.
Return value

Return the maximum of x and y.

Arcadia_minimum

Return the minimum of two values.

Type Arcadia_minimumSuffix(Type x, Type y)

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8ValueArcadia_Integer8Value
Integer16ValueArcadia_Integer16Value
Integer32ValueArcadia_Integer32Value
Integer64ValueArcadia_Integer64Value
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue
Parameters
Type xThe first value.
Type yThe second value.
Return value

Return the minimum of x and y.

Arcadia_nextPowerOfTwoGreaterThan

R provides functions returning the next power of two greater than a value.

Type Arcadia_nextPowerOfTwoGtSuffix(Type x)

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue
Parameters
Type xThe value.
Errors
Arcadia_Status_NotExistsThe next power of two greater than x is not representable by the type Type
Return value

Return the next power of two greater than x.

Arcadia_nextPowerOfTwoGreaterThanOrEqualTo

R provides functions returning the next power of two greater or equal to a value.

Type Arcadia_nextPowerOfTwoGteSuffix(Type x)

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue
Parameters
Type xThe value.
Errors
Arcadia_Status_NotExistsThe next power of two greater greater than or equal to x is not representable by the type Type
Return value

Return the next power of two greater than or equal to x.

Arcadia_safeAdd

Get the sum of two values.

void Arcadia_safeAddSuffix(Type augend, Typemv> addend, Type* sumHigh, Type* sumLow)

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
Natural8Value Arcadia_Natural8Value
SizeValue Arcadia_SizeValue
Parameters
Type augend The augend value.
Type addend The addend value.
Type* sumHighA pointer to a variable. The variable is assigned the high bits of the result.
Type* sumLow A pointer to a variable. The variable is assigned the low bits of the result.

Arcadia_safeMultiply

Get the product of two values.

void Arcadia_safeMultiplySuffix(Type x, Typemv> y)

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue
Parameters
Type xThe first value.
Type yThe second value.
Return value

Return the maximum of x and y.

R_getTickCount

Get the time, in milliseconds, since an unspecified moment in the past.

R_Natural64Value R_getTickCount()

Return value

The time, in milliseconds, since an unspecified momentn in the past.