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.
- The (sources of the) library resides in the directory https://github.com/michaelheilmann/michaelheilmann.com/tree/main/repository/Arcadia.Ring1/Library
- The (sources of) tests reside in the directory https://github.com/michaelheilmann/michaelheilmann.com/tree/main/repository/Arcadia.Ring1/Tests
- The (sources of this very documentation you are reading) documentation reside in the directory https://github.com/michaelheilmann/michaelheilmann.com/tree/main/repository/Arcadia.Ring1/Documentation
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
#define Arcadia_BooleanValue_True
is a value of the type denoting logically true
. It converts to 1
in arithmetic expressions.
#define Arcadia_BooleanValue_False
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
typedef
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
#define Arcadia_ForeignProcedureValue_NumberOfBits
denotes the number of Bits of the type.
#define Arcadia_ForeignProcedureValue_NumberOfBytes
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
where 8
, 16
, 32
, or 64
.
The macros in this section all include the 8
, 16
, 32
, and 64
of that meta variable.
#define Arcadia_Integer
denotes the number of Bits of the type. The value is always equal to the value of the respective
#define Arcadia_Integer
denotes the number of Bytes of the type which is usually Arcadia_Integer
divided by 8.
#define Arcadia_Integer
denotes the least value (in terms of its magnitude) representable by a the Arcadia_Integer
type.
The following table denotes the value of the constant for the respective
Value | |
8 | -128 |
16 | -32768 |
32 | -2147483648 |
64 | -9223372036854775808 |
#define Arcadia_Integer
denotes the greatest value (in terms of its magnitude) representable by a the Arcadia_Integer
type.
The following table denotes the value of the constant for the respective
Value | |
8 | 127 |
16 | 32767 |
32 | 2147483647 |
64 | 9223372036854775807 |
#define Arcadia_Integer
is used to write a literal of the type Arcadia_Integer
in C source code.
The following table denotes the expansions of the macro:
Value | |
8 | x |
16 | x |
32 | x |
64 | x##LL |
3.1.4. Natural Types
Arcadia Ring 1 provides natural number types.
typedef
where 8
, 16
, 32
, or 64
.
The macros in this section all include the 8
, 16
, 32
, and 64
of that meta variable.
#define Arcadia_Natural
denotes the number of Bits of the type. The value is always equal to the value of the respective
#define Arcadia_Integer
denotes the number of Bytes of the type which is usually Arcadia_Integer
divided by 8.
#define Arcadia_Natural
denotes the least value (in terms of its magnitude) representable by a the Arcadia_Natural
type.
The following table denotes the value of the constant for the respective
Value | |
8 | 0 |
16 | 0 |
32 | 0 |
64 | 0 |
#define Arcadia_Natural
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
Constant | Value |
8 | 255 |
16 | 65535 |
32 | 4294967295 |
64 | 18446744073709551615 |
#define Arcadia_Natual
is used to write a literal of the type Arcadia_Natural
in C source code.
The following table denotes the expansions of the macro:
Value | |
8 | x |
16 | x |
32 | x##U |
64 | x##ULL |
3.1.5. Object Reference Type
R provides a ObjectReference type.
typedef
The Arcadia_ObjectReferenceValue
type is a pointer.
A valid value of the Arcadia_ObjectReferenceValue
is the null reference
#define Arcadia_ObjectReferenceValue_Null
#define Arcadia_ObjectReferenceValue_NumberOfBits
denotes the number of Bits of the type.
#define Arcadia_ObjectReferenceValue_NumberOfBytes
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
#define Arcadia_SizeValue_NumberOfBits
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
denotes the number of Bytes of the type which is usually Arcadia_SizeValue_NumberOfBits
divided by 8.
#define Arcadia_SizeValue_Minimum
denotes the least value (in terms of its magnitude) representable by a the Arcadia_Size
type.
#define Arcadia_SizeValue_Literal(x)
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
The only value of this type is Arcadia_VoidValue_Void
.
Arcadia_VoidValue is an unsigned integral type.
#define Arcadia_VoidValue_Void
The single value of the type.
#define Arcadia_VoidValue_NumberOfBits
denotes the number of Bits of the type.
#define Arcadia_VoidValue_NumberOfBytes
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_ObjectReference | Arcadia_ObjectReferenceValue |
Arcadia_ValueTag_Size | Arcadia_SizeValue |
Arcadia_ValueTag_Void | Arcadia_VoidValue |
For each type, Arcadia_Value
has three functions associated:
bool Arcadia_Value_is
void Arcadia_Value_set
The following table lists the valid combinations of
Boolean | boolean |
Integer16 | integer16 |
Integer32 | integer32 |
Integer64 | integer64 |
Integer8 | integer8 |
Natural16 | natural16 |
Natural32 | natural32 |
Natural64 | natural64 |
Natural8 | natural8 |
ObjectReference | objectReference |
Size | size |
Void | void |
Arcadia_Value_is
returns true
if
the Arcadia_Value
stores a value of the type corresponding to false
.
Arcadia_Value_set
assigns the Arcadia_Value
a value of the type corresponding to
Arcadia_Value_get
get the value stored in
the Arcadia_Value
. The behavior of Arcadia_Value_set
is undefined if the value does not store a value of the
type corresponding to
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
Arcadia_Status
is a natural number type of a width of 32 Bit.
#definer Arcadia_Status_Success
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_
where 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 | 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). |
FileSystemOperationFailed | A 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
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)
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)) {
Arcadia_popJumpTarget();
} else {
Arcadia_popJumpTarget();
}
The if-branch is always entered at first as the Arcadia_JumpTarget_save()
at
its first invocation returns logically true. If the program at Arcadia_jump()
), then Arcadia_popJumpTarget();
and Arcadia_JumpTarget_save()
is re-evaluated and returns
logically false and Arcadia_popJumpTarget();
and
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.
The following table lists the combinations of
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
The value to clamp. | |
The lower bound (inclusive). | |
The upper bound (inclusive). |
This function returns the value value
clamped to the range [lower, upper]
.
Errors
Arcadia_Status_ArgumentValueInvalid | lower > 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_countLeadingZeroes
The following table lists the combinations of
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_hash
The following table lists the combinations of
BooleanValue | Arcadia_BooleanValue |
ForeignProcedureValue | Arcadia_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
The value. |
Return value
Return hash of x
.
Arcadia_maximum
Return the maximum of two values.
The following table lists the combinations of
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
The first value. | |
The second value. |
Return value
Return the maximum of x
and y
.
Arcadia_minimum
Return the minimum of two values.
The following table lists the combinations of
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
The first value. | |
The 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.
The following table lists the combinations of
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
The value. |
Errors
Arcadia_Status_NotExists | The next power of two greater than x is not representable by the 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.
The following table lists the combinations of
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
The value. |
Errors
Arcadia_Status_NotExists | The next power of two greater greater than or equal to x is not representable by the 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_safeAdd
The following table lists the combinations of
Natural16Value | Arcadia_Natural16Value |
Natural32Value | Arcadia_Natural32Value |
Natural64Value | Arcadia_Natural64Value |
Natural8Value | Arcadia_Natural8Value |
SizeValue | Arcadia_SizeValue |
Parameters
The augend value. | |
The addend value. | |
A pointer to a variable. The variable is assigned the high bits of the result. | |
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_safeMultiply
The following table lists the combinations of
Natural8Value | Arcadia_Natural8Value |
Natural16Value | Arcadia_Natural16Value |
Natural32Value | Arcadia_Natural32Value |
Natural64Value | Arcadia_Natural64Value |
SizeValue | Arcadia_SizeValue |
Parameters
The first value. | |
The 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.