Ajla tutorial

Contents

Introduction

Unpacking Ajla

Hello World

fn main(w : world, d : dhandle, h : list(handle), args : list(bytes),
	env : treemap(bytes, bytes)) : world
[
	w := write(w, h[1], "Hello World!" + nl);
	return w;
]

w : world

This is a token that must be passed to and returned from all functions that do I/O to sequence the I/O properly.

d : dhandle

This is a handle to the current working directory. The handle can be used when the user needs to open files relative to the working directory.

h : list(handle)

The list of handles that were passed to the program when it was executed. Usually, it contains 3 entries, the first for standard input, the second for standard output and the third for standard error.

args : list(bytes)

The arguments that were passed to the program. The type "bytes" represents a sequence of bytes, so list(bytes) is a list of sequences of bytes.

env : treemap(bytes, bytes)

This represents the environment variables for the program. The environment is represented as a tree that maps a sequence of bytes (i.e. the variable name) to another sequence of bytes (i.e. the variable content). This is implemented as an AVL tree, so that searching it is efficient.

w := write(w, h[1], "Hello World!" + nl);

This statement writes the string "Hello World!" and a newline to the handle 1 (standard output). The statement takes a w variable as an I/O token and returns the w variable back. Passing the world variable back and forth between functions that do I/O is required to maintain I/O ordering.

return w;

This statement returns the world variable to the caller.

Passing the world variable

fn main(w : world, d : dhandle, h : list(handle), args : list(bytes),
	env : treemap(bytes, bytes)) : world
[
	w := write(w, h[1], "Hello ");
	w := write(w, h[1], "World!");
	w := write(w, h[1], nl);
	return w;
]

Using implicit variables

fn main(implicit w : world, d : dhandle, h : list(handle), args : list(bytes),
	env : treemap(bytes, bytes)) : world
[
	write(h[1], "Hello ");
	write(h[1], "World!");
	write(h[1], nl);
]

Omitting the arguments

fn main
[
	write(h[1], "Hello World!" + nl);
]

Fizz-buzz

fn main
[
	for i := 1 to 101 do [
		if i mod 15 = 0 then write(h[1], "Fizz Buzz ");
		else if i mod 3 = 0 then write(h[1], "Fizz ");
		else if i mod 5 = 0 then write(h[1], "Buzz ");
		else write(h[1], ntos(i) + " ");
	]
	write(h[1], nl);
]

Statements

var x := 10;

Creates a variable and assigns a value to it. The type is inferred, if we don't want to infer the type, we use "var x : int := 10;"

x := 20;

Modifies the variable.

const x := 10;

Creates a constant and assigns a value to it. A constant can't be modified.

if condition then statement;
if condition then statement; else statement;

The "if" statement.

for i := 0 to 10 do statement;

The "for" statement. It iterates from 0 to 9.

for i in [ 10, 20, 30, 40 ] do statement;

The "for in" statement can iterate over a collection. In this example it iterates over a list that holds four values: 10, 20, 30, 40.

while condition do statement;

The "while" statement.

break;

Exits the current "for" or "while" loop.

continue;

Starts a new iteration of the current "for" or "while" loop.

return expression;

Exits the current function and returns the expression.

goto label;

The "goto" statement. It doesn't break purity, so it is allowed.

Types

int

A general integer number with arbitrary length. It is implemented as a 32-bit or 64-bit signed number. If some arithmetic operation overflows, it is converted to a long integer (using the gmp library) and the arithmetic is done with arbitrary precision.
On 32-bit architectures, int is 32-bit. On 64-bit architectures, int is 64-bit. On 64-bit architectures when the "--ptrcomp" switch is used, int is 32-bit. Note that these cases are semantically equivalent, because overflows are handled transparently.

int8, int16, int32, int64, int128

These types behave in the same way as the "int" type. The difference is in their implementation. int8 is implemented as an 8-bit integer and if it overflows, long integers using the gmp library are used. int16 is implemented as a 16-bit integer (with overflows handled by the gmp library), etc. If the compiler that was used to build Ajla doesn't support 128-bit integers, int128 is equivalent to int64.

sint8, sint16, sint32, sint64, sint128

This is a signed integer with a given size. If some arithmetic operation overflows, it is wrapped modulo the size. If the compiler doesn't support 128-bit integers, emulation using gmp is used.

uint8, uint16, uint32, uint64, uint128

This is an unsigned integer with a given size. If some arithmetic operation overflows, it is wrapped modulo the size. If the compiler doesn't support 128-bit integers, emulation using gmp is used.

real16, real32, real64, real80, real128

A floating point number with a given size. If the compiler has 128-bit floating point numbers and doesn't have 80-bit floating point numbers, then real80 is an alias for real128. If the compiler has neither 80-bit nor 128-bit floating point numbers, a slow software emulation is used.
Floating point constants can have a suffix that specifies the type — 'h' for real16, 's' for real32, no suffix for real64, 'l' for real80, 'q' for real128.

bool

A Boolean type — it can hold values true or false.

type

Ajla can pass types to functions as well as other values. We use the keyword type to specify that an argument is a type.

byte

An alias for uint8.

char

An alias for int32.

real

An alias for real64.

rational

A rational number — with an integer numerator and denominator. It is declared as:

record rational [
	num den : int;
]

fixed_point(base, digits)

A fixed point number with the specified base and the specified number of digits after the dot. The number of digits before the dot may be large — if it doesn't fit, the gmp library is used.

decimal(digits)

An alias for fixed_point(10, digits).

sint(bits)

A signed integer with the specified number of bits. If some arithmetic operation overflows, it is wrapped modulo the size.

uint(bits)

A unsigned integer with the specified number of bits. If some arithmetic operation overflows, it is wrapped modulo the size.

floating(ex_bits, sig_bits)

An arbitrary-precision floating-point number. The exponent has ex_bits and the mantissa has sig_bits.

list(t)

A list of elements where each element has a type t. Lists can be appended or sliced.

array(t, [ 10, 20, 30 ])

An array with arbitrary number of dimensions. In this example, it has three dimensions with the sizes 10, 20 and 30 elements. Arrays can't change their size after they are created.

record [ element1 : type1; element2 : type2; element3 : type3; ... ]

Record — it groups different types into a single type.

option [ element1 : type1; element2 : type2; element3 : type3; ... ]

An option holds only one of the specified types. In this example, it can hold either an element of the type type1 or an element of the type type2 or an element of the type type3.
There's an operator "is" that tests if the option holds a specified value. For example "o is element2" returns "true" if the option holds the value "element2".
There's an operator "ord" that returns the ordinal number of the value that the option holds (starting from 0). For example, if "o" holds the value "element3", then "ord o" returns the value 2.

bytes

An alias for list(byte).

string

An alias for list(char).

maybe(t)

It can hold either the value of type t or nothing. It is declared as:

option maybe(t : type) [
	j : t;
	n;
]

tuple2(t1, t2)

A tuple holding 2 values of types t1 and t2.

tuple3(t1, t2, t3)

A tuple holding 3 values of types t1, t2 and t3.

tuple4(t1, t2, t3, t4)

A tuple holding 4 values of the specified types.

tuple5(t1, t2, t3, t4, t5)

A tuple holding 5 values of the specified types. If you need larger tuples, you must declare them on your own with a record type.

treemap(key_type, value_type)

A key-value store with the specified key type and value type. It is implemented as an AVL tree.

treeset(key_type)

A set containing values of the specified type. It is implemented as an AVL tree.

heap(key_type)

A binary heap that can quickly insert an element or extract the lowest element. It is implemented as a list.

unit_type

This type may hold only one value — unit_value.

bottom_type

This type can't hold any value, it can only hold exceptions. It is used for functions that never return (for example for message loops). It is declared as:

option bottom_type [
]

Operators

Clauses

fn

Declares a function. For example:

fn maximum(a b : int) : int := select(a < b, a, b);

or

fn maximum(a b : int) : int
[
	if a < b then
		return b;
	else
		return a;
]

operator

Declares an operator with a given priority. For example, this declares a unary postfix operator "!" that calculates a factorial:

operator postfix ! 1000 (n : int) : int
[
	var v := 1;
	for i := 2 to n + 1 do
		v *= i;
	return v;
]

const

Declares a constant. A constant is a function that has no arguments. For example:

const ten := 10;
const hello := `Hello`;

type

Declares a type. For example type byte := uint8; declares the type "byte" as an alias to "uint8".

record

Declares a record. For example:

record person [
	name : string;
	surname : string;
	age : int;
]

option

Declares an option. For example:

option bool [
	false;
	true;
]

uses

Imports a unit from the standard library or from the program directory. For example "uses heap;" imports the file "stdlib/heap.ajla".

define

Defines a macro. See for example "define int_instance" from stdlib/system.ajla.

private

This declaration is only usable in the unit where it appears. It will not be imported to other units.

implicit

If you pass less arguments to a function than what was specified in the function header, the compiler will attempt to infer the remaining arguments. The "implicit" keyword makes this function a candidate for inferring.

conversion

This function converts one type to another. If there is a type mismatch, the compiler will scan all the "conversion" functions and try to resolve the mismatch automatically by adding the appropriate conversion.

Automatic parallelization

fn fib(n : int) : int
[
	if n <= 1 then
		return n;
	else
		return fib(n - 2) + fib(n - 1);
]

fn main
[
	var x := ston(args[0]);
	var f := fib(x);
	write(h[1], "fib " + ntos(x) + " = " + ntos(f) + nl);
]

Caching

fn fib~cache(n : int) : int
[
	if n <= 1 then
		return n;
	else
		return fib(n - 2) + fib(n - 1);
]

fn main
[
	var x := ston(args[0]);
	var f := fib(x);
	write(h[1], "fib " + ntos(x) + " = " + ntos(f) + nl);
]

Functions

Function call specifiers

~normal

Default — attempt to parallelize after two timer ticks

~strict

Don't attempt to parallelize

~spark

Parallelize immediately

~lazy

Evaluate when needed (like in Haskell)

~inline

Inline the function (i.e. insert it into the caller)

~cache

Cache the results

~save

Cache the results and save them to ~/.cache/ajla/

Nested functions

fn main
[
	fn sum(a b : int) : int
	[
		return a + b;
	]
	write(h[1], ntos(sum(10, 20)) + nl);
]

Lambda functions

fn main
[
	var l := [ 10, 15, 20, 25, 30, 35, 40 ];
	l := list_filter(l, lambda(x : int) [ return not x bt 0; ]);
	var add := 1;
	l := map(l, lambda(x : int) [ return x + add; ]);
	var m := map(l, lambda(x : int) [ return ntos(x); ]);
	write(h[1], list_join(m, nl));
]

11
21
31
41

Currying

fn main
[
	fn sum(a b : int) : int
	[
		return a + b;
	]
	var add_ten := sum(10,);
	write(h[1], ntos(add_ten(20)) + nl);
]

Lists

var l := list(int).[ 10, 20, 30, 40 ];

Creates a list with four members — 10, 20, 30, 40.

var l := [ 10, 20, 30, 40 ];

Creates a list with four members — 10, 20, 30, 40. We can omit the type of the list — the type will be derived from the type of the first member.

var l := empty(int);

Creates an empty list of integers.

var l := fill('a', 10);

Creates a list with 10 elements equal to 'a'.

var l := sparse('a', 1000000000);

Functionally, it is equivalent to fill. But unlike fill, sparse creates a compressed list that consumes little memory even when it is very large. If you modify the compressed list, it will be stored as a b+tree with consecutive runs of the same value compressed into a single b+tree node. Sparse lists are slower than flat lists because the virtual machine has to walk the b+tree on every access.

var l := [ 10, 20, 30, 40 ] + [ 50, 60, 70, 80 ];

Append two lists.

var l := [ 10, 20, 30, 40 ] <+ 50;

Append one value to a list.

var m := l[3];

Pick a member at index 3. The indices start from 0.

l[3] := 100;

Modify the list. If the list has a reference count different from 1, the copy of the list is created and modified. If the list has a reference count 1, it is modified in place.

var m := l[2 .. 4];

Take a slice of the list, starting with member 2 (inclusive) and ending with member 4 (exclusive).

var m := l[ .. 4];

Take a slice of the list, starting at the beginning of the list and ending with member 4 (exclusive).

var m := l[4 .. ];

Take a slice of the list, starting with member 4 (inclusive) and ending at the list end.

var a := len(l);

Get a length of the list.

var b := len_at_least(l, 10);

Returns true if the length is 10 or more elements.

var b := len_greater_than(l, 10);

Returns true if the length is greater than 10 elements.
len_at_least and len_greater_than are useful when dealing with infinite lists. We cannot use "if len(l) >= 10 then ..." on an infinite list, because it would attempt to evaluate the whole list and get into an infinite loop and memory hog. If we use "if len_at_least(l, 10) then ...", the virtual machine will attempt to evaluate the first 10 entries and it returns true without attempting to evaluate further entries.

for i in [ 10, 20, 30, 40 ] do ...

Iterate over a list. The loop body will be executed 4 times, with i being 10, 20, 30 and 40.

Infinite lists

fn inf_list~lazy(i : int) : list(int)
[
	return [ i ] + inf_list(i + 1);
]

fn main
[
	var l := inf_list(0);
	for e in l do
		write(h[1], ntos(e) + nl);
]

infinite(10)

Creates an infinite list containing the values 10.

infinite_repeat([ 1, 2, 3])

Creates an infinite list containing the values 1, 2, 3, 1, 2, 3, 1, 2, 3 ... etc.

infinite_uninitialized(int)

Creates an infinite lists with all members being exceptions. It may be useful to create associative arrays. You can test if a member is uninitialized with the function is_uninitialized.

Arrays

var a := array_fill(1, [ 3, 3, 3 ]);

Creates a three-dimensional array and fill it with value 1.

var a := array_sparse(1, [ 3, 3, 3 ]);

Functionally, it is equivalent to array_fill. But it creates a compressed array.

m := a[0, 1, 2];

Pick a value at a give index.

a[0, 1, 2] := 100;

Modify a value at a give index.

list_to_array

Converts a list to an array.

array_to_list

Converts an array to a list.

Strings

uses charset;

fn main
[
	var loc := locale_console_init(env);
	write(h[1], string_to_locale(loc, `Mikuláš Patočka`) + nl);
]

Exceptions

	if is_exception x then
		write(h[1], "Exception occurred" + nl);
	else
		write(h[1], "There's no exception, the value is " + ntos(x) + nl);

Class

ec_sync, ec_async, ec_syscall or ec_exit

ec_sync

The exception happened due to execution of the program. For example, invalid numeric calculation or index out of array/list size.

ec_async

The exception happened due to conditions not related to the program. For example, memory allocation failure falls into this category.

ec_syscall

The exception happened because some syscall failed.

ec_exit

The exception holds the return value that should be returned when the program exits.

Type

This is an exception code. Exception types are listed in the file stdlib/ex_codes.ajla — see the constants "error_*".

Code

This is auxiliary value. It's meaning depends on the exception type.

Type: error_system

Code is one of the system_error_* values.

Type: error_errno

Code is the errno value.

Type: error_os2

Code is the OS/2 error number.

Type: error_os2_socket

Code is the OS/2 socket error number.

Type: error_win32

Code is the Windows error number.

Type: error_h_errno

Code is the h_errno error number.

Type: error_gai

Code is the getaddrinfo return value.

Type: error_subprocess

Code is the subprocess exit number, if the code is negative, it is the signal number that terminated the subprocess.

Type: error_exit

Code is the return value that should be returned from the current process.

Operators that examine exceptions

is_exception

Returns true if the argument is an exception.

exception_class

Returns class of an exception.

exception_type

Returns type of an exception.

exception_aux

Returns auxiliary value of an exception.

exception_string

Returns a string representing the type and aux values, you can use it to display the exception to the user.

exception_payload

Returns the raw string attached to the exception.

exception_stack

Returns the stack trace attached to the exception.

Function that manipulate exceptions

exception_make

Makes an exception with the given class, type and code and optional stack trace.

exception_make_str

Makes an exception with the given class, type, code and string and optional stack trace.

exception_copy

Copies the exception from a variable s that has a type src_type to the return value that has a type dst_type. The variable s must hold an exception, if not, invalid operation exception is returned.

Statements that manipulate exceptions

eval expression

Evaluate a given expression (or more expressions separated by a comma), and discards the result. It may be used to print debugging messages, for example eval debug("message"). The debug statement writes the message to the standard error handle.

xeval expression

Evaluate a given expression (or more expressions separated by a comma). If the result is non-exception, the result is discarded. If the result is an exception, the current function is terminated and the exception is returned as a return value.

abort

Terminate the current function with with ec_sync, error_abort.

abort expression

Evaluate a given expression (or more expressions separated by a comma). If the result is an exception, the current function is terminated and the exception is returned as a return value. If the result is non-exception, the current function exits with ec_sync, error_abort. It may be used with the statement "internal" to terminate the whole process if some internal error happens — abort internal("this shouldn't happen").

keep variables

Doesn't evaluate the variables, it just marks the variables as live, so that the optimizer won't discard them.

Syntax errors

fn syntax_error : int
[
	bla bla bla;
]

fn main
[
	var q := syntax_error;
	if is_exception q then [
		write(h[1], "Exception happened" + nl);
	]
]

I/O

Read mode

The handle is being read sequentially

Write mode

The handle is being written sequentially

Block mode

You can perform read and write operations on arbitrary offsets in the file. This mode only works for files and block devices.

fn ropen(w : world, d : dhandle, f : bytes, flags : int) : (world, handle);

This function will open a file in a read mode and return a handle to the file. w is the world token, d is the base directory that is used for file name lookup, f is the file name, flags is one of the open_flag_* flags. For this function, only the flag open_flag_no_follow is allowed.

fn read(w : world, h : handle, size : int) : (world, bytes);

Read the specified number of bytes from the handle. If end-of-file is detected, it returns less bytes. If not enough bytes is available (in case of a pipe or a character device), the function will sleep until the specified number of bytes is read.

fn read_partial(w : world, h : handle, size : int) : (world, bytes);

Read the specified number of bytes from the handle. If not enough bytes are available, the function returns less bytes. If no bytes are available, the function sleeps until at least one byte is returned.

---

fn wopen(w : world, d : dhandle, f : bytes, flags : int, mode : int) : (world, handle);

Opens a file in a write mode and return a handle to it. flags contain one or more of open_flag_append, open_flag_create, open_flag_must_create, open_flag_no_follow. open_flag_append specifies that we want to append to the file rather than overwrite it, open_flag_create specifies that we want to create the file if it doesn't exist, open_flag_must_create specifies that we want to fail with an error if the file exists, open_flag_no_follow suppresses the dereferencing of the last symlink in a file name. mode represents the permissions of the file if it is created, it may be open_mode_ro_current_user, open_mode_ro_all_users, open_mode_rw_current_user, open_mode_read_all_users, open_mode_default or other value.

fn write(w : world, h : handle, s : bytes) : world;

Writes the bytes to the write handle.

fn wcontiguous(w : world, h : handle, size : int64) : world;

Allocates a contiguous space for size bytes. Only some of the operating systems (Linux and OS/2) support preallocation of file data. If the operating system doesn't support it, the function returns with success and does nothing.

fn pipe(w : world) : (world, handle, handle);

Creates a pipe and returns two handles. The first handle is used for reading from the pipe and the second handle is used for writing to the pipe.

---

fn bopen(w : world, d : dhandle, f : bytes, flags : int, mode : int) : (world, handle);

Opens a file in a block mode. flags is a combination of open_flag_*. mode represents the permissions of the file if it is created.

fn bread(w : world, h : handle, position : int64, size : int) : (world, bytes);

Read bytes from the specified position. If end-of-file is encountered, the function returns less bytes.

fn bwrite(w : world, h : handle, position : int64, s : bytes) : world;

Write bytes to the specified position. If we write beyond file end, the file is extended.

fn bsize(w : world, h : handle) : (world, int64);

Returns the size of the file.

fn bdata(w : world, h : handle, off : int64) : (world, int64);

Skips over a hole in the file. Returns a next offset where some data are allocated. Some filesystems do not support holes; for them this function returns off.

fn bhole(w : world, h : handle, off : int64) : (world, int64);

Skips over data in the file. Returns a next offset where there is a hole in the file. Some filesystems do not support holes; for them this function returns

fn bsetsize(w : world, h : handle, size : int64) : world;

Truncates a file to the specified size or extends it.

fn bcontiguous(w : world, h : handle, pos : int64, size : int64) : world;

Allocates a contiguous space at the specified offset. Some operating systems do not support file preallocation, for them, this function return success without doing anything.

fn bclone(w : world, src_h : handle, src_pos : int64, dst_h : handle, dst_pos : int64, size : int64) : world;

Clones a byte range from src_h starting at src_pos to dst_h starting at dst_pos. Only some filesystems support cloning, if the filesystem doesn't support it, an error is reported.

---

fn droot(w : world) : dhandle;

Returns a handle to the root directory. On Windows or OS/2, it returns a handle to C:\.

fn dnone(w : world) : dhandle;

Returns an invalid directory handle. It is useful if you want to open a file and you know that the file path is absolute — in this case, you can pass dnone() to ropen, wopen, bopen or dopen.

fn dopen(w : world, d : dhandle, f : bytes, flags : int) : (world, dhandle);

Open a directory that is relative to an existing directory. The only allowed flag is open_flag_no_follow.

fn dread(w : world, d : dhandle) : (world, list(bytes));

Reads the directory and returns the list of directory entries.

fn dpath(w : world, d : dhandle) : (world, bytes);

Returns a path that the directory points to. Note that we cannot return a path for file handles, because there may be multiple names referring to a single inode.

fn dmonitor(w : world, d : dhandle) : (world, world);

Monitor the specified directory for changes. If the operating system doesn't support directory monitoring, exception is returned. If the operating system supports directory monitoring, the first value is returned immediately and the second value is returned when the directory changed.

I/O error handling

fn main
[
	var old_w := w;
	var x1 := ston(args[0]);
	var x2 := ston(args[1]);
	write(h[1], ntos(x1) + " / " + ntos(x2) + " = " + ntos(x1 div x2) + nl);
	if is_exception w then [
		var msg := exception_string w;
		recover_world(old_w);
		write(h[1], "An exception " + msg + " happened and was recovered" + nl);
	]
]

Lazy functions for I/O

fn main
[
	var lines := list_break_to_lines(read_lazy(h[0]));
	for line in lines do [
		write(h[1], "read a line: """ + line + """." + nl);
	]
	write(h[1], "read all the lines, exiting..." + nl);
]

Units

unit fibunit;

fn fib(n : int) : int;

implementation

fn fib(n : int) : int
[
        if n <= 1 then
                return n;
        else
                return fib(n - 2) + fib(n - 1);
]

uses fibunit;

fn main
[
        var x := ston(args[0]);
        var f := fib(x);
        write(h[1], "fib " + ntos(x) + " = " + ntos(f) + nl);
]

Name clashes

Hiding the implementations of types

type heap(key : type, cls : class_ord(key));

type heap(key : type, cls : class_ord(key)) := list(key);

Type classes

fn matmult(const n : int, a b : array(real64, [n, n])) : array(real64, [n, n])
[
	var result := array_fill(0., [n, n]);
	for i := 0 to n do
		for j := 0 to n do
			for k := 0 to n do
				result[i, j] += a[i, k] * b[k, j];
	return result;
]

fn matmult~inline(t : type, implicit cls : class_unit_ring(t), const n : int,
		  a b : array(t, [n, n])) : array(t, [n, n])
[
	var result := array_fill(cls.zero, [n, n]);
	for i := 0 to n do
		for j := 0 to n do
			for k := 0 to n do
				result[i, j] += a[i, k] * b[k, j];
	return result;
]

record class_unit_ring(t : type) [
	add : fn(t, t) : t;
	zero : t;
	neg : fn(t) : t;
	subtract : fn(t, t) : t;
	multiply : fn(t, t) : t;
	one : t;
]

	var m1 : array(real32, [ 10, 10 ]);
	var m2 : array(real32, [ 10, 10 ]);
	... fill m1 and m2 with some data ...
	var m3 := matmult(m1, m2);

Standard type classes

Threads

fn main
[
	for i := 1 to 11 do [
		w := sleep(w, 1000000);
		w := write(w, h[1], ntos(i) + nl);
	]
]

fn main
[
	var w1, w2 := fork(w);
	for i := 1 to 11 do [
		w1 := sleep(w1, 1000000);
		w1 := write(w1, h[1], "thread 1: " + ntos(i) + nl);
	]
	for i := 1 to 11 do [
		w2 := sleep(w2, 1000000);
		w2 := write(w2, h[1], "thread 2: " + ntos(i) + nl);
	]
	w := join(w1, w2);
]

thread 1: 1
thread 2: 1
thread 1: 2
thread 2: 2
thread 1: 3
thread 2: 3
thread 1: 4
thread 2: 4
thread 1: 5
thread 2: 5
thread 1: 6
thread 2: 6
thread 1: 7
thread 2: 7
thread 1: 8
thread 2: 8
thread 1: 9
thread 2: 9
thread 1: 10
thread 2: 10

fn main
[
	var w1, w2 := fork(w);
	for i := 1 to 11 do [
		w1 := sleep~spark(w1, 1000000);
		w1 := write~spark(w1, h[1], "thread 1: " + ntos(i) + nl);
	]
	for i := 1 to 11 do [
		w2 := sleep~spark(w2, 1000000);
		w2 := write~spark(w2, h[1], "thread 2: " + ntos(i) + nl);
	]
	w := join(w1, w2);
]

Infinite loops

fn main
[
	while true do [
		w := write(w, h[1], "Hello World!" + nl);
	]
	return w;
]

fn main
[
	while true do [
		w := write(w, h[1], "Hello World!" + nl);
		xeval w;
	]
	return w;
]

fn main
[
	while not is_exception w do [
		w := write(w, h[1], "Hello World!" + nl);
	]
	return w;
]

Other thread functions

any

Start evaluating both values and wait until any of them becomes evaluated. Returns "false" if the first value is evaluated and "true" if the second value is evaluated. If both of them are evaluated, "false" is returned.

any_list

Start evaluating all the values in the list and wait until any of the becomes evaluated. Returns the index of the first value that is evaluated.

is_ready

Returns "true" if the value is evaluated.

never

Blocks and never completes.

atomic_enter

Increases the atomic count — when the atomic count is non-zero, the thread will not be killed.

atomic_exit

Decreases the atomic count — when the atomic count is zero, the thread may be killed if its return value is not used.

Message queues

msgqueue_new

Creates a new message queue holding entries of the specified type.

msgqueue_send

Sends a message to the message queue. Every message has a tag and a value. The tag may be used to filter messages on the receive side.

msgqueue_replace

Replace the content of the queue with a given message.

msgqueue_receive

Waits until the queue is non-empty and returns the first message.

msgqueue_receive_tag

Waits until the queue has at least one message with a given tag and returns this message.

msgqueue_receive_nonblock

If the queue is non-empty, return the first message, otherwise return the exception "error_not_found".

msgqueue_receive_tag_nonblock

If the queue contains a message with the specified tag, return it, otherwise return the exception "error_not_found".

msgqueue_peek_nonblock

Return a message without removing it from the queue. If the queue is empty, the exception "error_not_found" is returned.

msgqueue_peek_tag_nonblock

Return a message with the specified tag without removing it from the queue. If there is no such message, the exception "error_not_found" is returned.

msgqueue_wait

Wait until the queue becomes non-empty.

msgqueue_is_nonempty

Returns true if the queue is non-empty.

msgqueue_any

Wait until any of the two message queues becomes non-empty.

uses ui.termcap;
uses ui.event;

fn main
[
	var tc := termcap_init(d, env);
	var loc := locale_console_init(env);
	var q := msgqueue_new(event);
	var kbd_thread := event_get_keyboard(h[0], tc, loc, q);
	while not is_exception w do [
		var tag, e := msgqueue_receive(q);
		if e is keyboard then [
			write(h[1], "keyboard event " + ntos(e.keyboard.key) + ", " + ntos(e.keyboard.flags) + nl);
			if e.keyboard.key = 'q' then break;
		]
		keep kbd_thread;
	]
]

var tc := termcap_init(d, env);

Initialize the termcap database and store it to the variable "tc".

var loc := locale_console_init(env);

Initialize the locale according to environment variables.

var q := msgqueue_new(event);

Create a message queue of events. "event" is defined in the file "stdlib/ui/event.ajla".

var kbd_thread := event_get_keyboard(h[0], tc, loc, q);

Create a thread that reads the keyboard from handle 0. "tc" is the termcap database, "loc" is the current locale and "q" is the message queue, where events will be sent.

while not is_exception w do

Loop while there is no exception.

var tag, e := msgqueue_receive(q);

Read the message queue; wait if it is empty.

if e is keyboard then

If the event is a keyboard event, take this branch.

write(h[1], "keyboard event " + ntos(e.keyboard.key) + ", " + ntos(e.keyboard.flags) + nl);

Print the keyboard event.

if e.keyboard.key = 'q' then break;

Exit if the user pressed 'q'.

keep kbd_thread;

This statement prevents the optimizer from removing the thread. Without this statement, the optimizer would conclude that the variable "kbd_thread" is not used anymore, it would free it and that would terminate the "event_get_keyboard" thread.

FFI

uses ffi;

fn main
[
	var str := "Hello World!" + nl;
	var destr := ffi_destructor_new();
	var message := ffi_destructor_allocate(destr, len(str), 1, false);
	ffi_poke_array(message, str);
	var wrt := ffi_create_function("", "write", ffi_error.e_errno, 3,
		ffi_type.t_ssize, [ffi_type.t_sint, ffi_type.t_pointer, ffi_type.t_usize ]);
	var xh := ffi_handle_to_number(destr, h[1]);
	var r, e := ffi_call_function(wrt, [ xh, message, len(str) ]);
	ffi_destructor_destroy(destr);
	if r = -1 then [
		write(h[2], "error " + ntos(e) + " occurred" + nl);
		exit(1);
	] else if r <> len(str) then [
		write(h[2], "wrote only " + ntos(r) + " bytes" + nl);
		exit(1);
	]
]

var str := "Hello World!" + nl;

The string to be written.

var destr := ffi_destructor_new();

This line allocates a destructor. So far, it is empty, so no operation is done when the destructor is freed.

var message := ffi_destructor_allocate(destr, len(str), 1, false);

This line allocates memory from the destructor and returns a pointer to the allocated memory. len(str) is the size of the allocated memory, 1 is the alignment of the memory, false specifies that the memory doesn't have to be cleared. When the destr variable is freed, the allocated memory is automatically freed as well.

ffi_poke_array(message, str);

This copies the string to the pointer returned by the previous function. Note that the function ffi_poke_array may be used to overwrite arbitrary memory in the process.

var wrt := ffi_create_function("", "write", ffi_error.e_errno, 3, ffi_type.t_ssize, [ffi_type.t_sint, ffi_type.t_pointer, ffi_type.t_usize ]);

This statement loads a pointer to the function "write" from the standard library. The first argument is a library name (empty string for libc), the second argument is the name of the function, the third argument specifies that we are interested in the errno value returned by the function, the fourth argument is the number of fixed arguments, the fifth argument is the return type, the sixth argument is the list containing types for the three arguments — the first argument has type signed integer, the second argument has type pointer, the third argument has type unsigned size_t.

var xh := ffi_handle_to_number(destr, h[1]);

This statement converts an Ajla handle to a system handle. The result will be "1" because we are writing to the standard output. A reference to the handle is stored in the destructor, so that it will be dropped when the destructor is dropped.

var r, e := ffi_call_function(wrt, [ xh, message, len(str) ]);

Call the "write" function, r is the return value, e is the errno value.

ffi_destructor_destroy(destr);

This function indicates that the destr variable should be freed at this point. If we didn't use ffi_destructor_destroy(destr), the destr variable would be freed when it goes out of scope (i.e. after the call to ffi_handle_to_number) and the function ffi_call_function would access invalid memory and invalid handle.

if r = -1 then ...

The rest of the program prints an error if the write failed.

Performance considerations

--profile=function

It will count how many times each function is called and the time spent in the function and it will display the functions sorted by the time.

--profile=escape

It will show locations where escape from the machine code to the interpreter happened. It shows the function, the line number, the number of escapes and the opcode that triggered the escape.

--profile=memory

It will show where memory was allocated.

--profile

Enable "function", "escape" and "memory".

eval report_memory_summary("hello");

Report the summary of allocated memory, for example "DEBUG MESSAGE: allocated memory at hello: 689030 / 4054 = 169".

eval report_memory_most("hello");

Report locations where most memory was allocated, for example this "DEBUG MESSAGE: pcode.c:3298 284314 / 234 = 1215" means that there is 284314 bytes in 234 blocks allocated at pcode.c:3298.

eval report_memory_largest("hello");

Report the largest allocated blocks, for example this "DEBUG MESSAGE: pcode.c:3298 35378" means that there is a block of 35378 bytes being allocated at pcode.c:3298.

Other options

--compile

Compile the whole program without running it. It is useful if you need to check the source code for syntax errors. Without this switch, the program is being compiled as it runs and syntax errors in unused parts of the program are not reported.

--nosave

Do not save and load compiled code. This option also inhibits saving and loading cache of functions with the ~save specifier.

--ptrcomp

Use pointer compression — pointers will have only 32 bits and the maximum allocatable memory is 32GiB. It reduces memory consumption slightly.

--strict-calls

Turn off auto-parallelization. It is useful if you want to get longer stack trace for debugging purposes. Normally, the stack trace is chopped at a point where auto-parallelization happens.

--system-malloc

Use system malloc instead of Ajla malloc. It reduces memory consumption, and it decreases performance slightly.

--thread-tick

Use a thread for timer ticks instead of using a signal.

--threads=n

Use the specified number of threads. By default, Ajla detects the number of hardware threads in the system and uses this value.

--tick=n

The timer tick in microseconds. By default, it is 10000. If you specify too small value, you should enable --thread-tick as well. If the tick value is smaller that the time it takes to process a signal, the signal would be hammering the worker threads so heavily, that they can't make any progress.

Hacking Ajla

Configure options

--enable-threads=pthread

Compile with pthreads (default, if pthreads are detected).

--enable-threads=win32

Compile with Windows threads.

--disable-threads

Compile without threads.

--disable-computed-goto

Don't use computed goto. By default, computed goto is used if the compiler supports it.

--enable-bitwise-frame

Use bitwise tags on the stack rather than byte tags. It may or may not improve performance depending on the actual workload. By default, bitwise tags are disabled, because they perform slightly worse.

--enable-debuglevel=0

No debugging at all.

--enable-debuglevel=1

Default option. This enables debugging assertions in non-performance-critical parts of the code. It also enables "--debug" command line flags that turn on debugging of various subsystems of Ajla.

--enable-debuglevel=2

This enables all debugging assertions even in performance-critical parts of the code.

--enable-debuglevel=3

This enables all debugging checks that degrade performance seriously.

Debugging options

--debug=magic

Put a magic value at the start every memory block. The magic value is verified when reallocating or freeing the block. If there is a mismatch, internal error is reported and the core is dumped.

--debug=redzone

Put a redzone value at the end of every memory block and verify it when reallocating or freeing the block.

--debug=fill

Fill the allocated and freed blocks with a byte pattern.

--debug=leak

Maintain a list of allocated blocks and test for memory leaks when Ajla exits. It will display a file and line of the allocation that leaked.

--debug=memory

Enable "magic, redzone, fill, leak".

--debug=mutex-errorcheck

Set the pthread attribute PTHREAD_MUTEX_ERRORCHECK on mutexes.

--debug=mutex

Check the correct usage of mutexes. Also, enable "mutex-errorcheck".

--debug=cond

Check the correct usage of condition variables.

--debug=thread

Check the correct usage of threads.

--debug=tls

Check the correct usage of thread-local storage.

--debug=handles

Check the correct usage of handles.

--debug=objects

Enable "mutex-errorcheck, mutex, cond, thread, tls, handles".

--debug

Enable all debugging options.

Rebuilding the standard library