texts/tutorial.html

   1 <html>
   2 <head>
   3 <title>Ajla tutorial</title>
   4 </head>
   5 <!--
   6  * Copyright (C) 2024 Mikulas Patocka
   7  *
   8  * This file is part of Ajla.
   9  *
  10  * Ajla is free software: you can redistribute it and/or modify it under the
  11  * terms of the GNU General Public License as published by the Free Software
  12  * Foundation, either version 3 of the License, or (at your option) any later
  13  * version.
  14  *
  15  * Ajla is distributed in the hope that it will be useful, but WITHOUT ANY
  16  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  17  * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along with
  20  * Ajla. If not, see <https://www.gnu.org/licenses/>.
  21 -->
  22 <body>
  23 <h1><center>Ajla tutorial</center></h1>
  24
  25 <h2>Contents</h2>
  26 <a href="#introduction">Introduction</a><br>
  27 <a href="#hello_world">Hello World</a><br>
  28 <a href="#fizz_buzz">Fizz-buzz</a><br>
  29 <a href="#statements">Statements</a><br>
  30 <a href="#types">Types</a><br>
  31 <a href="#operators">Operators</a><br>
  32 <a href="#clauses">Clauses</a><br>
  33 <a href="#automatic_parallelization">Automatic parallelization</a><br>
  34 <a href="#caching">Caching</a><br>
  35 <a href="#functions">Functions</a><br>
  36 <a href="#lists">Lists</a><br>
  37 <a href="#arrays">Arrays</a><br>
  38 <a href="#strings">Strings</a><br>
  39 <a href="#exceptions">Exceptions</a><br>
  40 <a href="#i_o">I/O</a><br>
  41 <a href="#units">Units</a><br>
  42 <a href="#type_classes">Type classes</a><br>
  43 <a href="#threads">Threads</a><br>
  44 <a href="#ffi">FFI</a><br>
  45 <a href="#performance_considerations">Performance considerations</a><br>
  46 <a href="#hacking_ajla">Hacking Ajla</a><br>
  47
  48 <h2 id=introducton>Introduction</h2>
  49
  50 Ajla is a purely functional programming language that has look-and-feel like
  51 traditional imperative languages. The return value of every function in Ajla
  52 depends only on its arguments. Ajla has mutable local variables and control flow
  53 statements (if, while, for, goto) that are known from imperative languages. Ajla
  54 doesn't have mutable global variables because they break purity and they may be
  55 subject to race conditions.
  56 <br>
  57 <br>
  58 Ajla is memory-safe &mdash; i.e. you can't create a segmentation fault in Ajla.
  59 Ajla doesn't have garbage collection; it uses reference counts to track
  60 allocated memory. Ajla has mutable arrays &mdash; if the array reference count
  61 is one, it is mutated in place, if it is different from one, a copy of the array
  62 is created.
  63
  64 <h3 id=unpacking>Unpacking Ajla</h3>
  65 Before compiling Ajla, install the packages libgmp-dev and libffi-dev. If
  66 libgmp-dev is not installed, Ajla will use slow built-in version. If libffi-dev
  67 is not installed, the possibility to call C functions from Ajla will be
  68 disabled.
  69 <br>
  70 <br>
  71 Download the newest Ajla version from the
  72 <a href="https://www.ajla-lang.cz/downloads/">downloads</a> directory. Unpack
  73 the tar.gz archive and compile it with <code>./configure && make</code>. Install
  74 it with <code>make install</code>.
  75 <br>
  76 <br>
  77 If you cloned the git repository, there is no <code>./configure</code> script.
  78 You can generate it with the <code>./rebuild</code> script. You need autoconf,
  79 automake and ed installed.
  80 <br>
  81 <br>
  82 It is recommended to use gcc &mdash the compilation will take several minutes
  83 and it will consume about 4GB memory when compiling the files ipret.c and
  84 ipretc.c. Compilation with clang works, but it is very slow, it may take an hour
  85 or more to compile the files ipret.c and ipretc.c.
  86 <br>
  87 <br>
  88 When running Ajla programs, it is recommended to set the cpu governor to
  89 'performance'. Ajla starts and stops threads rapidly and the 'ondemand' governor
  90 underclocks the cores, resulting in slower performance.
  91 <br>
  92 <br>
  93 You can compile and run a program directly by executing "<code>ajla
  94 program.ajla</code>". The program will be compiled as it runs and the result
  95 will be saved in the file <code>~/.cache/ajla/program.sav</code>. When you run
  96 the program second time, it will be faster because there will be no compilation.
  97 If you change the source code file, the cache file will be invalidated and the
  98 program will be compiled again.
  99 <br>
 100 <br>
 101 There's a <code>--compile</code> switch &mdash; it will compile the whole
 102 program without running it and save it to the <code>~/.cache/ajla</code>
 103 directory. You should use this switch when you are developing a program, because
 104 it will scan all the source code units and look for syntax errors.
 105 <br>
 106 <br>
 107 The standard library is placed in the <code>stdlib</code> subdirectory, you can
 108 read it to find out what types and functions are there. The
 109 <code>system.ajla</code> file is implicitly included before compiling any Ajla
 110 source file.
 111 <br>
 112 <br>
 113 In "<code>programs/acmd/</code>" there's Ajla Commander &mdash; a Midnight
 114 Commander clone written in Ajla. You can run it with "<code>./ajla
 115 programs/acmd/acmd.ajla</code>".
 116
 117 <h2 id=hello_world>Hello World</h2>
 118
 119 Programming language tutorials usually start with a program that prints "Hello
 120 World". Let's have look at "Hello World" in Ajla:
 121
 122 <pre id=hw1>
 123 fn main(w : world, d : dhandle, h : list(handle), args : list(bytes),
 124         env : treemap(bytes, bytes)) : world
 125 [
 126         w := write(w, h[1], "Hello World!" + nl);
 127         return w;
 128 ]
 129 </pre>
 130
 131 Copy this piece of code to a file "hello.ajla" and run "ajla hello.ajla" to
 132 execute it.
 133
 134 <br>
 135 <br>
 136
 137 Here we declare a function main with the following arguments. The symbol before
 138 the dot is the name of the argument and the expression after the dot is the type
 139 of the argument.
 140 <dl>
 141 <dt><code>w : world</code>
 142 <dd>This is a token that must be passed to and returned from all functions that
 143 do I/O to sequence the I/O properly.
 144 <dt><code>d : dhandle</code>
 145 <dd>This is a handle to the current working directory. The handle can be used
 146 when the user needs to open files relative to the working directory.
 147 <dt><code>h : list(handle)</code>
 148 <dd>The list of handles that were passed to the program when it was executed.
 149 Usually, it contains 3 entries, the first for standard input, the second for
 150 standard output and the third for standard error.
 151 <dt><code>args : list(bytes)</code>
 152 <dd>The arguments that were passed to the program. The type "<code>bytes</code>"
 153 represents a sequence of bytes, so <code>list(bytes)</code> is a list of
 154 sequences of bytes.
 155 <dt><code>env : treemap(bytes, bytes)</code>
 156 <dd>This represents the environment variables for the program. The environment
 157 is represented as a tree that maps a sequence of bytes (i.e. the variable name)
 158 to another sequence of bytes (i.e. the variable content). This is implemented as
 159 an AVL tree, so that searching it is efficient.
 160 </dl>
 161 The function contains the following statements:
 162 <dl>
 163 <dt><code>w := write(w, h[1], "Hello World!" + nl);</code>
 164 <dd>This statement writes the string <i>"Hello World!"</i> and a newline to the
 165 handle 1 (standard output). The statement takes a <code>w</code> variable as an
 166 I/O token and returns the <code>w</code> variable back. Passing the world
 167 variable back and forth between functions that do I/O is required to maintain
 168 I/O ordering. <dt><code>return w;</code>
 169 <dd>This statement returns the world variable to the caller.
 170 </dl>
 171
 172 <h3>Passing the world variable</h3>
 173 In order to show how the world passing works, let's split the "Hello World"
 174 program to three write statements.
 175
 176 <pre id=hw2>
 177 fn main(w : world, d : dhandle, h : list(handle), args : list(bytes),
 178         env : treemap(bytes, bytes)) : world
 179 [
 180         w := write(w, h[1], "Hello ");
 181         w := write(w, h[1], "World!");
 182         w := write(w, h[1], nl);
 183         return w;
 184 ]
 185 </pre>
 186
 187 In a functional language that has non-strict evaluation, we can't just do I/O
 188 anywhere because the I/Os could be reordered or not executed at all. We need
 189 some mechanism to maintain I/O ordering. Haskell uses monads to maintain I/O
 190 ordering, Ajla uses a different mechanism &mdash; world passing. Every function
 191 that performs I/O takes "world" as an argument and returns "world" as a return
 192 value (functions can have multiple return values in Ajla). The "world" variable
 193 makes sure that the functions can't be reordered. In this example, <code>w :=
 194 write(w, h[1], nl)</code> may be executed only after <code>w := write(w, h[1],
 195 "World!")</code> finished. And <code>w := write(w, h[1], "World!")</code> may be
 196 executed only after <code>w := write(w, h[1], "Hello ")</code> finished.
 197
 198 <h3>Using implicit variables</h3>
 199 Now, let's have look at another Ajla feature &mdash; implicit variables. We add
 200 the <code>implicit</code> keyword to the function argument <code>w :
 201 world</code> and we drop the <code>w</code> variable from the code that does
 202 writes.
 203
 204 <pre>
 205 fn main(<b>implicit</b> w : world, d : dhandle, h : list(handle), args : list(bytes),
 206         env : treemap(bytes, bytes)) : world
 207 [
 208         write(h[1], "Hello ");
 209         write(h[1], "World!");
 210         write(h[1], nl);
 211 ]
 212 </pre>
 213
 214 If a variable is declared as <code>implicit</code>, the compiler will
 215 automatically add the variable to the function calls where does it fit. The
 216 <code>write</code> function should have three arguments, here it has only two
 217 arguments, so the compiler will search for all implicit variables and it will
 218 use an implicit variable that fits into the remaining argument.
 219 <br>
 220 <br>
 221 If we don't specify a return value for the <code>write</code> function call, the
 222 compiler will search for all implicit variables and assign the return value to a
 223 variable where does it fit.
 224 <br>
 225 <br>
 226 If we don't use the <code>return</code> statement at the end of the function,
 227 the compiler will search for implicit variables and automatically return a
 228 variable that fits into the return value.
 229 <br>
 230 <br>
 231 Here we can see that with the implicit variables the code really looks as if it
 232 were written in a procedural programming language. But it is not procedural
 233 &mdash; the code is translated to <a href="#hw2">this</a> and that is what is
 234 running on the virtual machine.
 235
 236 <h3>Omitting the arguments</h3>
 237 The compiler already knows what arguments should the <code>main</code> function
 238 have, so you can omit them. So, we can simplify our program to this:
 239
 240 <pre>
 241 fn main
 242 [
 243         write(h[1], "Hello World!" + nl);
 244 ]
 245 </pre>
 246
 247 This is the simplest way how to write a "Hello World" program in Ajla.
 248 Internally, it is translated to <a href="#hw1">this</a>.
 249
 250 <h2 id=fizz_buzz>Fizz-buzz</h2>
 251
 252 Fizz-buzz is another standard programming test. The goal is to write a program
 253 that iterates from 1 to 100. If the number is divisible by 3, "Fizz" is written;
 254 if the number is divisible by 5, "Buzz" is written, otherwise the number is
 255 written.
 256
 257 <pre>
 258 fn main
 259 [
 260         for i := 1 to 101 do [
 261                 if i mod 15 = 0 then write(h[1], "Fizz Buzz ");
 262                 else if i mod 3 = 0 then write(h[1], "Fizz ");
 263                 else if i mod 5 = 0 then write(h[1], "Buzz ");
 264                 else write(h[1], ntos(i) + " ");
 265         ]
 266         write(h[1], nl);
 267 ]
 268 </pre>
 269
 270 The <code>for</code> statement iterates a variable over a given range. The
 271 starting value is inclusive, the ending value is exclusive &mdash; thus, if we
 272 want to iterate from 1 to 100, we need to specify 1 and 101. The operator
 273 <code>mod</code> is an arithmetic remainder, the <code>if</code> statements test
 274 if the value is divisible by 15, 3 and 5. If it is not divisible by these
 275 numbers, we print the number; the <code>ntos</code> function converts a number
 276 to a string.
 277
 278 <br>
 279 <br>
 280
 281 You can see that it looks very much like a procedural language.
 282
 283 <h2 id=statements>Statements</h2>
 284
 285 Ajla has the following statements:
 286 <dl>
 287 <dt><code>var x := 10;</code>
 288 <dd>Creates a variable and assigns a value to it. The type is inferred, if we
 289 don't want to infer the type, we use "<code>var x : int := 10;</code>"
 290 <dt><code>x := 20;</code>
 291 <dd>Modifies the variable.
 292 <dt><code>const x := 10;</code>
 293 <dd>Creates a constant and assigns a value to it. A constant can't be modified.
 294 <dt>
 295 <code>if condition then statement;</code>
 296 <br>
 297 <code>if condition then statement; else statement;</code>
 298 <dd>The "if" statement.
 299 <dt><code>for i := 0 to 10 do statement;</code>
 300 <dd>The "for" statement. It iterates from 0 to 9.
 301 <dt><code>for i in [ 10, 20, 30, 40 ] do statement;</code>
 302 <dd>The "for in" statement can iterate over a collection. In this example it
 303 iterates over a list that holds four values: 10, 20, 30, 40.
 304 <dt><code>while condition do statement;</code>
 305 <dd>The "while" statement.
 306 <dt><code>break;</code>
 307 <dd>Exits the current "for" or "while" loop.
 308 <dt><code>continue;</code>
 309 <dd>Starts a new iteration of the current "for" or "while" loop.
 310 <dt><code>return expression;</code>
 311 <dd>Exits the current function and returns the expression.
 312 <dt><code>goto label;</code>
 313 <dd>The "goto" statement. It doesn't break purity, so it is allowed.
 314 </dl>
 315 The <code>if</code> and <code>while</code> statements can accept multiple
 316 expressions separated by a comma &mdash; in this case, the expressions are
 317 evaluated from the first to the last and if one of them is evaluated as
 318 <code>false</code>, the evaluation is terminated and the conditional branch is
 319 not taken.
 320 <br>
 321 <br>
 322 The assignment also accepts multiple expressions &mdash; for example, "<code>x,
 323 y := y, x</code>" will swap the variables <code>x</code> and <code>y</code>.
 324
 325 <h2 id=types>Types</h2>
 326
 327 Ajla has the following primitive types:
 328 <dl>
 329 <dt><code>int</code>
 330 <dd>A general integer number with arbitrary length. It is implemented as a
 331 32-bit or 64-bit signed number. If some arithmetic operation overflows, it is
 332 converted to a long integer (using the gmp library) and the arithmetic is done
 333 with arbitrary precision.
 334 <br>
 335 On 32-bit architectures, <code>int</code> is 32-bit. On 64-bit architectures,
 336 <code>int</code> is 64-bit. On 64-bit architectures when the
 337 "<code>--ptrcomp</code>" switch is used, <code>int</code> is 32-bit. Note that
 338 these cases are semantically equivalent, because overflows are handled
 339 transparently.
 340 <dt><code>int8</code>, <code>int16</code>, <code>int32</code>,
 341 <code>int64</code>, <code>int128</code>
 342 <dd>These types behave in the same way as the "int" type. The difference is in
 343 their implementation. <code>int8</code> is implemented as an 8-bit integer and
 344 if it overflows, long integers using the gmp library are used.
 345 <code>int16</code> is implemented as a 16-bit integer (with overflows handled by
 346 the gmp library), etc. If the compiler that was used to build Ajla doesn't
 347 support 128-bit integers, <code>int128</code> is equivalent to
 348 <code>int64</code>.
 349 <dt><code>sint8</code>, <code>sint16</code>, <code>sint32</code>,
 350 <code>sint64</code>, <code>sint128</code>
 351 <dd>This is a signed integer with a given size. If some arithmetic operation
 352 overflows, it is wrapped modulo the size. If the compiler doesn't support
 353 128-bit integers, emulation using gmp is used.
 354 <dt><code>uint8</code>, <code>uint16</code>, <code>uint32</code>,
 355 <code>uint64</code>, <code>uint128</code>
 356 <dd>This is an unsigned integer with a given size. If some arithmetic operation
 357 overflows, it is wrapped modulo the size. If the compiler doesn't support
 358 128-bit integers, emulation using gmp is used.
 359 <dt><code>real16</code>, <code>real32</code>, <code>real64</code>,
 360 <code>real80</code>, <code>real128</code>
 361 <dd>A floating point number with a given size. If the compiler has 128-bit
 362 floating point numbers and doesn't have 80-bit floating point numbers, then
 363 <code>real80</code> is an alias for <code>real128</code>. If the compiler has
 364 neither 80-bit nor 128-bit floating point numbers, a slow software emulation is
 365 used.
 366 <br>
 367 Floating point constants can have a suffix that specifies the type &mdash; 'h'
 368 for real16, 's' for real32, no suffix for real64, 'l' for real80, 'q' for
 369 real128.
 370 <dt><code>bool</code>
 371 <dd>A Boolean type &mdash; it can hold values <code>true</code> or
 372 <code>false</code>.
 373 <dt><code>type</code>
 374 <dd>Ajla can pass types to functions as well as other values. We use the keyword
 375 <code>type</code> to specify that an argument is a type.
 376 </dl>
 377 The following types are defined in the standard library:
 378 <dl>
 379 <dt><code>byte</code>
 380 <dd>An alias for <code>uint8</code>.
 381 <dt><code>char</code>
 382 <dd>An alias for <code>int32</code>.
 383 <dt><code>real</code>
 384 <dd>An alias for <code>real64</code>.
 385 <dt><code>rational</code>
 386 <dd>A rational number &mdash; with an integer numerator and denominator. It is
 387 declared as:
 388 <pre>
 389 record rational [
 390         num den : int;
 391 ]
 392 </pre>
 393 <dt><code>fixed_point(base, digits)</code>
 394 <dd>A fixed point number with the specified base and the specified number of
 395 digits after the dot. The number of digits before the dot may be large &mdash;
 396 if it doesn't fit, the gmp library is used.
 397 <dt><code>decimal(digits)</code>
 398 <dd>An alias for <code>fixed_point(10, digits)</code>.
 399 <dt><code>sint(bits)</code>
 400 <dd>A signed integer with the specified number of bits. If some arithmetic
 401 operation overflows, it is wrapped modulo the size.
 402 <dt><code>uint(bits)</code>
 403 <dd>A unsigned integer with the specified number of bits. If some arithmetic
 404 operation overflows, it is wrapped modulo the size.
 405 <dt><code>floating(ex_bits, sig_bits)</code>
 406 <dd>An arbitrary-precision floating-point number. The exponent has
 407 <code>ex_bits</code> and the mantissa has <code>sig_bits</code>.
 408 </dl>
 409 Ajla has the following composite types:
 410 <dl>
 411 <dt><code>list(t)</code>
 412 <dd>A list of elements where each element has a type <code>t</code>. Lists can
 413 be appended or sliced.
 414 <dt><code>array(t, [ 10, 20, 30 ])</code>
 415 <dd>An array with arbitrary number of dimensions. In this example, it has three
 416 dimensions with the sizes 10, 20 and 30 elements. Arrays can't change their size
 417 after they are created.
 418 <dt><code>record [ element1 : type1; element2 : type2; element3 : type3; ...
 419 ]</code>
 420 <dd>Record &mdash; it groups different types into a single type.
 421 <dt><code>option [ element1 : type1; element2 : type2; element3 : type3; ...
 422 ]</code>
 423 <dd>An option holds only one of the specified types. In this example, it can
 424 hold either an element of the type <code>type1</code> or an element of the type
 425 <code>type2</code> or an element of the type <code>type3</code>.
 426 <br>
 427 There's an operator "<code>is</code>" that tests if the option holds a specified
 428 value. For example "<code>o is element2</code>" returns "<code>true</code>" if
 429 the option holds the value "<code>element2</code>".
 430 <br>
 431 There's an operator "<code>ord</code>" that returns the ordinal number of the
 432 value that the option holds (starting from 0). For example, if "<code>o</code>"
 433 holds the value "<code>element3</code>", then "<code>ord o</code>" returns the
 434 value 2.
 435 </dl>
 436 The following composite types are defined in the standard library:
 437 <dl>
 438 <dt><code>bytes</code> <dd>An alias for <code>list(byte)</code>.
 439 <dt><code>string</code>
 440 <dd>An alias for <code>list(char)</code>.
 441 <dt><code>maybe(t)</code>
 442 <dd>It can hold either the value of type <code>t</code> or nothing. It is
 443 declared as:
 444 <pre>
 445 option maybe(t : type) [
 446         j : t;
 447         n;
 448 ]
 449 </pre>
 450 <dt><code>tuple2(t1, t2)</code>
 451 <dd>A tuple holding 2 values of types <code>t1</code> and <code>t2</code>.
 452 <dt><code>tuple3(t1, t2, t3)</code>
 453 <dd>A tuple holding 3 values of types <code>t1</code>, <code>t2</code> and
 454 <code>t3</code>.
 455 <dt><code>tuple4(t1, t2, t3, t4)</code>
 456 <dd>A tuple holding 4 values of the specified types.
 457 <dt><code>tuple5(t1, t2, t3, t4, t5)</code>
 458 <dd>A tuple holding 5 values of the specified types. If you need larger tuples,
 459 you must declare them on your own with a <code>record</code> type.
 460 <dt><code>treemap(key_type, value_type)</code>
 461 <dd>A key-value store with the specified key type and value type. It is
 462 implemented as an AVL tree.
 463 <dt><code>treeset(key_type)</code>
 464 <dd>A set containing values of the specified type. It is implemented as an AVL
 465 tree.
 466 <dt><code>heap(key_type)</code>
 467 <dd>A binary heap that can quickly insert an element or extract the lowest
 468 element. It is implemented as a list.
 469 <dt><code>unit_type</code>
 470 <dd>This type may hold only one value &mdash; unit_value.
 471 <dt><code>bottom_type</code>
 472 <dd>This type can't hold any value, it can only hold exceptions. It is used for
 473 functions that never return (for example for message loops). It is declared as:
 474 <pre>
 475 option bottom_type [
 476 ]
 477 </pre>
 478 </dl>
 479
 480 <h2 id=operators>Operators</h2>
 481
 482 <table border=1>
 483 <tr><th>Operator<th>Priority<th>Description</tr>
 484 <tr><td>Unary <code>+</code><td>1000<td>It just returns the passed value</tr>
 485 <tr><td>Unary <code>-</code><td>1000<td>Negation</tr>
 486 <tr><td><code>*</code><td>2000<td>Multiplication</tr>
 487 <tr><td><code>/</code><td>2000<td>Floating point division</tr>
 488 <tr><td><code>div</code><td>2000<td>Integer division</tr>
 489 <tr><td><code>mod</code><td>2000<td>Integer remainder</tr>
 490 <tr><td><code>+</code><td>3000<td>Addition (or append when applied to lists)</tr>
 491 <tr><td><code>-</code><td>3000<td>Subtraction</tr>
 492 <tr><td><code>x +&lt; y</code><td>3000<td>Append a value <code>y</code> to the list <code>x</code></tr>
 493 <tr><td><code>shl</code><td>4000<td>Bit shift left</tr>
 494 <tr><td><code>shr</code><td>4000<td>Bit shift right</tr>
 495 <tr><td><code>rol</code><td>4000<td>Bit rotation left</tr>
 496 <tr><td><code>ror</code><td>4000<td>Bit rotation right</tr>
 497 <tr><td><code>x bts y</code><td>4000<td>Set <code>y</code>-th bit in <code>x</code></tr>
 498 <tr><td><code>x btr y</code><td>4000<td>Clear <code>y</code>-th bit in <code>x</code></tr>
 499 <tr><td><code>x btc y</code><td>4000<td>Invert <code>y</code>-th bit in <code>x</code></tr>
 500 <tr><td><code>x bt y</code><td>4000<td>Test if <code>y</code>-th bit in <code>x</code> is set</tr>
 501 <tr><td>Unary <code>bswap</code><td>4000<td>Reverse bytes in a number</tr>
 502 <tr><td>Unary <code>brev</code><td>4000<td>Reverse bits in a number</tr>
 503 <tr><td>Unary <code>bsf</code><td>4000<td>Finds the lowest set bit</tr>
 504 <tr><td>Unary <code>bsr</code><td>4000<td>Finds the highest set bit</tr>
 505 <tr><td>Unary <code>popcnt</code><td>4000<td>Count the number of set bits</tr>
 506 <tr><td>Unary <code>is_negative</code><td>5000<td>Test if a real number is negative</tr>
 507 <tr><td>Unary <code>is_infinity</code><td>5000<td>Test if a real number is infinite</tr>
 508 <tr><td>Unary <code>is_exception</code><td>5000<td>Test if a value is an exception</tr>
 509 <tr><td><code>=</code><td>6000<td>Test for equality</tr>
 510 <tr><td><code>&lt;&gt;</code><td>6000<td>Test for non-equality</tr>
 511 <tr><td><code>&gt;</code><td>6000<td>Test if the first argument is greater</tr>
 512 <tr><td><code>&gt;=</code><td>6000<td>Test if the first argument is greater or equal</tr>
 513 <tr><td><code>&lt;</code><td>6000<td>Test if the first argument is less</tr>
 514 <tr><td><code>&lt;=</code><td>6000<td>Test if the first argument is less or equal</tr>
 515 <tr><td><code>not</code><td>7000<td>Logical negation</tr>
 516 <tr><td><code>and</code><td>8000<td>Logical and</tr>
 517 <tr><td><code>xor</code><td>9000<td>Logical exclusive or</tr>
 518 <tr><td><code>or</code><td>10000<td>Logical or</tr>
 519 </table>
 520 If we pass different types to an operator, the second argument is converted to a
 521 type of the first argument. For example <code>2.5 + 1</code> will return a
 522 floating point value <code>3.5</code>. <code>1 + 2.5</code> will return an
 523 integer value <code>3</code>.
 524
 525 <h2 id=clauses>Clauses</h2>
 526
 527 Every Ajla source file consists of clauses. This is the list of the clauses:
 528 <dl>
 529 <dt><code>fn</code>
 530 <dd>Declares a function. For example:
 531 <pre>
 532 fn maximum(a b : int) : int := select(a < b, a, b);
 533 </pre>
 534 or
 535 <pre>
 536 fn maximum(a b : int) : int
 537 [
 538         if a < b then
 539                 return b;
 540         else
 541                 return a;
 542 ]
 543 </pre>
 544 <dt><code>operator</code>
 545 <dd>Declares an operator with a given priority. For example, this declares a
 546 unary postfix operator "<code>!</code>" that calculates a factorial:
 547 <pre>
 548 operator postfix ! 1000 (n : int) : int
 549 [
 550         var v := 1;
 551         for i := 2 to n + 1 do
 552                 v *= i;
 553         return v;
 554 ]
 555 </pre>
 556 <dt><code>const</code>
 557 <dd>Declares a constant. A constant is a function that has no arguments. For
 558 example:
 559 <pre>
 560 const ten := 10;
 561 const hello := `Hello`;
 562 </pre>
 563 <dt><code>type</code>
 564 <dd>Declares a type. For example <code>type byte := uint8;</code> declares the
 565 type "<code>byte</code>" as an alias to "<code>uint8</code>".
 566 <dt><code>record</code>
 567 <dd>Declares a record. For example:
 568 <pre>
 569 record person [
 570         name : string;
 571         surname : string;
 572         age : int;
 573 ]
 574 </pre>
 575 <dt><code>option</code>
 576 <dd>Declares an option. For example:
 577 <pre>
 578 option bool [
 579         false;
 580         true;
 581 ]
 582 </pre>
 583 <dt><code>uses</code>
 584 <dd>Imports a unit from the standard library or from the program directory. For
 585 example "<code>uses heap;</code>" imports the file
 586 "<code>stdlib/heap.ajla</code>".
 587 <dt><code>define</code>
 588 <dd>Defines a macro. See for example "<code>define int_instance</code>" from
 589 <code>stdlib/system.ajla</code>.
 590 </dl>
 591 Function, const and type declarations may be prefixed with:
 592 <dl>
 593 <dt><code>private</code>
 594 <dd>This declaration is only usable in the unit where it appears. It will not be
 595 imported to other units.
 596 <dt><code>implicit</code>
 597 <dd>If you pass less arguments to a function than what was specified in the
 598 function header, the compiler will attempt to infer the remaining arguments. The
 599 "<code>implicit</code>" keyword makes this function a candidate for inferring.
 600 <dt><code>conversion</code>
 601 <dd>This function converts one type to another. If there is a type mismatch, the
 602 compiler will scan all the "<code>conversion</code>" functions and try to
 603 resolve the mismatch automatically by adding the appropriate conversion.
 604 </dl>
 605
 606 <h2 id=automatic_parallelization>Automatic parallelization</h2>
 607
 608 Let's have a look at this program that does Fibonacci number calculation. It is
 609 deliberately written in an inefficient recursive way.
 610
 611 <pre id=fib>
 612 fn fib(n : int) : int
 613 [
 614         if n &lt;= 1 then
 615                 return n;
 616         else
 617                 return fib(n - 2) + fib(n - 1);
 618 ]
 619
 620 fn main
 621 [
 622         var x := ston(args[0]);
 623         var f := fib(x);
 624         write(h[1], "fib " + ntos(x) + " = " + ntos(f) + nl);
 625 ]
 626 </pre>
 627
 628 If you run this program with some higher value, for example 45, you will notice
 629 that all the cores are busy. That's because Ajla does automatic parallelization.
 630 <br>
 631 <br>
 632 How does automatic parallelization work? We should parallelize only functions
 633 that take long time. If we parallelized every function call, the overhead of the
 634 parallelization would cause massive slowdown.
 635 <br>
 636 <br>
 637 <img src=parallel.svg alt="Automatic parallelization" width=100%>
 638 <br>
 639 <br>
 640 Ajla scans the stack every tick (by default, the tick is 10ms, it can be changed
 641 with the <code>--tick</code> argument). If some function stays on the stack for
 642 two ticks, it took long enough and it can be parallelized. For example, suppose
 643 that "Frame 4" in this diagram is there for 2 timer ticks. The stack is broken
 644 down into two stacks and both of these stacks are executed concurrently. The
 645 function "Frame 3" in the upper stack needs some return value, but we don't know
 646 the return value yet (the return value would be returned by the topmost function
 647 in the lower stack) &mdash; so we return a structure called <i>thunk</i> to the
 648 upper stack. If the lowermost function in the upper stack attempts to evaluate
 649 the thunk, it waits for the lower stack to finish (in this situation,
 650 parallelization is not possible). If the lowermost function in the upper stack
 651 doesn't attempt to evaluate the thunk, both stacks run concurrently.
 652 <br>
 653 <br>
 654 Automatic parallelization can be disabled with the "<code>--strict-calls</code>"
 655 switch.
 656
 657 <h2 id=caching>Caching</h2>
 658
 659 Let's have a look at the Fibonacci number example again:
 660
 661 <pre>
 662 fn fib<b>~cache</b>(n : int) : int
 663 [
 664         if n &lt;= 1 then
 665                 return n;
 666         else
 667                 return fib(n - 2) + fib(n - 1);
 668 ]
 669
 670 fn main
 671 [
 672         var x := ston(args[0]);
 673         var f := fib(x);
 674         write(h[1], "fib " + ntos(x) + " = " + ntos(f) + nl);
 675 ]
 676 </pre>
 677
 678 We added a <code>~cache</code> specifier to the function fib. Because Ajla is
 679 purely functional, every function will return the same value if the same
 680 arguments are supplied. Thus, we can cache the return values. This is what the
 681 <code>~cache</code> specifier does.
 682 <br>
 683 <br>
 684 Now, you can see that you can pass large values to the function and the function
 685 will complete quickly. That's because the Ajla virtual machine remembers what
 686 value was returned for what argument and if you call the function again with the
 687 same argument, it will just return a cached value.
 688 <br>
 689 <br>
 690 In this example, the caching just turned an algorithm with O(2<sup>n</sup>)
 691 complexity to an algorithm with O(n&nbsp;log&nbsp;n) complexity. The cache is
 692 implemented as a red-black tree, so operations on it have logarithmic
 693 complexity.
 694
 695 <h2 id=functions>Functions</h2>
 696
 697 <h3>Function call specifiers</h3>
 698 Ajla has the following function call specifiers:
 699 <dl>
 700 <dt><code>~normal</code>
 701 <dd>Default &mdash; attempt to parallelize after two timer ticks
 702 <dt><code>~strict</code>
 703 <dd>Don't attempt to parallelize
 704 <dt><code>~spark</code>
 705 <dd>Parallelize immediately
 706 <dt><code>~lazy</code>
 707 <dd>Evaluate when needed (like in Haskell)
 708 <dt><code>~inline</code>
 709 <dd>Inline the function (i.e. insert it into the caller)
 710 <dt><code>~cache</code>
 711 <dd>Cache the results
 712 <dt><code>~save</code>
 713 <dd>Cache the results and save them to <code>~/.cache/ajla/</code>
 714 </dl>
 715 The specifiers may be specified either at function declaration or at function
 716 call. If different specifiers are specified at function declaration and at
 717 function call, the specifier from the function call wins.
 718
 719 <h3>Nested functions</h3>
 720 Functions may be nested. The nested function has access to variables of the
 721 parent function that were visible at the point where the nested function was
 722 declared. If the variable is later changed in the parent function, the change is
 723 not promoted to the nested function. If the variable is later changed in the
 724 nested function, the change is not promoted to the parent function. This is an
 725 example of a nested function:
 726 <pre>
 727 fn main
 728 [
 729         fn sum(a b : int) : int
 730         [
 731                 return a + b;
 732         ]
 733         write(h[1], ntos(sum(10, 20)) + nl);
 734 ]
 735 </pre>
 736 Nested functions can't be recursive.
 737
 738 <h3>Lambda functions</h3>
 739 Lambda functions are anonymous functions that are declared inside an expression
 740 in the parent function. Like nested functions, they may use parent function
 741 variables that were visible when the lambda function was declared. This is an
 742 example of lambda functions:
 743 <pre>
 744 fn main
 745 [
 746         var l := [ 10, 15, 20, 25, 30, 35, 40 ];
 747         l := list_filter(l, lambda(x : int) [ return not x bt 0; ]);
 748         var add := 1;
 749         l := map(l, lambda(x : int) [ return x + add; ]);
 750         var m := map(l, lambda(x : int) [ return ntos(x); ]);
 751         write(h[1], list_join(m, nl));
 752 ]
 753 </pre>
 754 We start with a list of seven elements: 10, 15, 20, 25, 30, 35, 40. The function
 755 "<code>list_filter</code>" takes a list and a function that returns a Boolean
 756 value and returns the elements for which the function returned
 757 <code>"true"</code>. In this example, it selects even numbers (the operator
 758 "<code>bt 0</code>" tests if bit 0 is set). So, the list has now only four
 759 elements: 10, 20, 30, 40. The function "<code>map</code>" takes a list and a
 760 function, applies the function to every element of the list and returns the list
 761 of the results. In this example, the first "<code>map</code>" function will add
 762 1 to every element of the list. The next "<code>map</code>" takes a list and
 763 applies the "<code>ntos</code>" function to every element of the list &mdash;
 764 i.e. it converts the list of numbers to the list of byte strings. The
 765 "<code>list_join</code>" function joins the byte strings and separates them with
 766 the second arguments &mdash; that is a newline. The program will print this:
 767 <pre>
 768 11
 769 21
 770 31
 771 41
 772 </pre>
 773
 774 <h3>Currying</h3>
 775 Currying is the operation where we take a function, pass fewer arguments to the
 776 function than what was specified in the function header and create a new
 777 function that takes the remaining arguments. In Ajla, currying is done by
 778 passing empty arguments from the right end of the argument list.
 779 <pre>
 780 fn main
 781 [
 782         fn sum(a b : int) : int
 783         [
 784                 return a + b;
 785         ]
 786         var add_ten := sum(10,);
 787         write(h[1], ntos(add_ten(20)) + nl);
 788 ]
 789 </pre>
 790 For example, here we have a function "<code>sum</code>" that takes two arguments
 791 and returns their sum. If we write "<code>sum(10,)</code>", we create a new
 792 function that takes one argument and adds the value 10 to the argument. We
 793 assign this new function to the variable "<code>add_ten</code>". Finally, we
 794 call "<code>add_ten(20)</code>", which returns the value 30.
 795
 796 <h2 id=lists>Lists</h2>
 797
 798 <code>list(t)</code> represents a list type whose elements have a type of
 799 <code>t</code>. All the elements in a list must have the same type.
 800 <dl>
 801 <dt><code>var l := list(int).[ 10, 20, 30, 40 ];</code>
 802 <dd>Creates a list with four members &mdash; 10, 20, 30, 40.
 803 <dt><code>var l := [ 10, 20, 30, 40 ];</code>
 804 <dd>Creates a list with four members &mdash; 10, 20, 30, 40. We can omit the
 805 type of the list &mdash; the type will be derived from the type of the first
 806 member.
 807 <dt><code>var l := empty(int);</code>
 808 <dd>Creates an empty list of integers.
 809 <dt><code>var l := fill('a', 10);</code>
 810 <dd>Creates a list with 10 elements equal to 'a'.
 811 <dt><code>var l := sparse('a', 1000000000);</code>
 812 <dd>Functionally, it is equivalent to <code>fill</code>. But unlike
 813 <code>fill</code>, <code>sparse</code> creates a compressed list that consumes
 814 little memory even when it is very large. If you modify the compressed list, it
 815 will be stored as a b+tree with consecutive runs of the same value compressed
 816 into a single b+tree node. Sparse lists are slower than flat lists because the
 817 virtual machine has to walk the b+tree on every access.
 818 <dt><code>var l := [ 10, 20, 30, 40 ] + [ 50, 60, 70, 80 ];</code>
 819 <dd>Append two lists.
 820 <dt><code>var l := [ 10, 20, 30, 40 ] <+ 50;</code>
 821 <dd>Append one value to a list.
 822 <dt><code>var m := l[3];</code>
 823 <dd>Pick a member at index 3. The indices start from 0.
 824 <dt><code>l[3] := 100;</code>
 825 <dd>Modify the list. If the list has a reference count different from 1, the
 826 copy of the list is created and modified. If the list has a reference count 1,
 827 it is modified in place.
 828 <dt><code>var m := l[2 .. 4];</code>
 829 <dd>Take a slice of the list, starting with member 2 (inclusive) and ending with
 830 member 4 (exclusive).
 831 <dt><code>var m := l[ .. 4];</code>
 832 <dd>Take a slice of the list, starting at the beginning of the list and ending
 833 with member 4 (exclusive).
 834 <dt><code>var m := l[4 .. ];</code>
 835 <dd>Take a slice of the list, starting with member 4 (inclusive) and ending at
 836 the list end.
 837 <dt><code>var a := len(l);</code>
 838 <dd>Get a length of the list.
 839 <dt><code>var b := len_at_least(l, 10);</code>
 840 <dd>Returns true if the length is 10 or more elements.
 841 <dt><code>var b := len_greater_than(l, 10);</code>
 842 <dd>Returns true if the length is greater than 10 elements.
 843 <br>
 844 <code>len_at_least</code> and <code>len_greater_than</code> are useful when
 845 dealing with infinite lists. We cannot use "<code>if len(l) >= 10 then
 846 ...</code>" on an infinite list, because it would attempt to evaluate the whole
 847 list and get into an infinite loop and memory hog. If we use "<code>if
 848 len_at_least(l, 10) then ...</code>", the virtual machine will attempt to
 849 evaluate the first 10 entries and it returns <code>true</code> without
 850 attempting to evaluate further entries.
 851 <dt><code>for i in [ 10, 20, 30, 40 ] do ...</code>
 852 <dd>Iterate over a list. The loop body will be executed 4 times, with
 853 <code>i</code> being 10, 20, 30 and 40.
 854 </dl>
 855
 856 <h3>Infinite lists</h3>
 857 This is an example that creates an infinite list, iterates over it and prints
 858 the result.
 859 <pre>
 860 fn inf_list~lazy(i : int) : list(int)
 861 [
 862         return [ i ] + inf_list(i + 1);
 863 ]
 864
 865 fn main
 866 [
 867         var l := inf_list(0);
 868         for e in l do
 869                 write(h[1], ntos(e) + nl);
 870 ]
 871 </pre>
 872 Note that we must not use <code>len(list)</code> because it would force
 873 evaluation of the whole list &mdash; such evaluation never finishes and it blows
 874 memory.
 875 <br>
 876 <br>
 877 Infinite lists can be created with these functions:
 878 <dl>
 879 <dt><code>infinite(10)</code>
 880 <dd>Creates an infinite list containing the values 10.
 881 <dt><code>infinite_repeat([ 1, 2, 3])</code>
 882 <dd>Creates an infinite list containing the values 1, 2, 3, 1, 2, 3, 1, 2, 3 ...
 883 etc.
 884 <dt><code>infinite_uninitialized(int)</code>
 885 <dd>Creates an infinite lists with all members being exceptions. It may be
 886 useful to create associative arrays. You can test if a member is uninitialized
 887 with the function <code>is_uninitialized</code>.
 888 </dl>
 889
 890 <h2 id=arrays>Arrays</h2>
 891
 892 <code>array(t, shape)</code> represents an array type whose elements have a type
 893 of <code>t</code>. <code>shape</code> is a list of integers that represents
 894 dimensions of the array.
 895 <dl>
 896 <dt><code>var a := array_fill(1, [ 3, 3, 3 ]);</code>
 897 <dd>Creates a three-dimensional array and fill it with value 1.
 898 <dt><code>var a := array_sparse(1, [ 3, 3, 3 ]);</code>
 899 <dd>Functionally, it is equivalent to array_fill. But it creates a compressed
 900 array.
 901 <dt><code>m := a[0, 1, 2];</code>
 902 <dd>Pick a value at a give index.
 903 <dt><code>a[0, 1, 2] := 100;</code>
 904 <dd>Modify a value at a give index.
 905 <dt><code>list_to_array</code>
 906 <dd>Converts a list to an array.
 907 <dt><code>array_to_list</code>
 908 <dd>Converts an array to a list.
 909 </dl>
 910 Note: arrays are just syntactic sugar for lists. Internally, the virtual machine
 911 treats arrays as if they were lists.
 912
 913
 914 <h2 id=strings>Strings</h2>
 915
 916 Ajla has two kinds of strings. Byte strings are represented by the type
 917 "<code>bytes</code>" which is an alias for "<code>list(byte)</code>" which is an
 918 alias for "<code>list(uint8)</code>". Character strings are represented by the
 919 type "<code>string</code>", which is an alias for "<code>list(char)</code>"
 920 which is an alias for "<code>list(int32)</code>".
 921 <br>
 922 <br>
 923 Character constants are specified using single quotes, for example
 924 <code>'C'</code>. Byte constants can be specified using quotation marks, for
 925 example <code>"hello"</code>. String constants are specified using backquotes,
 926 for example <code>`Hello`</code>. String constants are always considered as
 927 UTF-8, regardless of the system locale &mdash; so that if the user moves the
 928 source file between systems with different locales, we get consistent result.
 929 <br>
 930 <br>
 931 For byte strings, the characters are stored system-defined locale. It is usually
 932 UTF-8, but it may be different, depending on the operating system and the
 933 "<code>LANG</code>" variable.
 934 <br>
 935 <br>
 936 The character strings are stored in Unicode. They use the "<code>int32</code>"
 937 type &mdash; that is arbitrary-precision integer. If there are Unicode combining
 938 characters, they are not stored as a separate character, they are superimposed
 939 to the character they belong to. In the unit <code>charset</code>, there is
 940 "<code>const combining_shift : char := 21</code> &mdash; that means that a
 941 combining character is shifted by 21 bits to the left and added to the base
 942 character. The reason why is it done this way is to make sure that text editors
 943 can treat each "<code>char</code>" as one visible character and they don't have
 944 to deal with combining characters in their logic.
 945 <br>
 946 <br>
 947 The unit <code>charset</code> (<code>stdlib/charset.ajla</code>) contains the
 948 conversion routines between ascii, utf-8, locale-specific encoding and strings.
 949 If we want to write or read strings, we need to convert them to or from bytes
 950 using the system locale. The system locale is obtained with the function
 951 <code>locale_init</code> or <code>locale_console_init</code>. These functions
 952 are almost equivalent, the only difference is on Windows 9x, where locale_init
 953 returns the ANSI character set and locale_console_init returns the OEM character
 954 set. On Windows NT, both of these functions return UTF-8 locale and the Ajla
 955 runtime will translate UTF-8 names to UTF-16 names that are used by the Windows
 956 NT syscalls. On Unix-based systems, both of these functions return the character
 957 set as set by the variables "<code>LC_ALL</code>", "<code>LC_CTYPE</code>" or
 958 "<code>LANG</code>" and there is no translation of byte strings when they are
 959 passed to syscalls.
 960 <br><br>
 961 For example, this program converts my name to the system locale and prints it:
 962 <pre>
 963 uses charset;
 964
 965 fn main
 966 [
 967         var loc := locale_console_init(env);
 968         write(h[1], string_to_locale(loc, `Mikul&aacute;&scaron; Pato&ccaron;ka`) + nl);
 969 ]
 970 </pre>
 971 The first statement loads the current locale based on the environment variables
 972 being set. The function <code>string_to_locale</code> will covert the
 973 <code>string</code> to <code>bytes</code> represented by the current locale. It
 974 will work not only on UTF-8 system, but on ISO-8895-2 system as well. If the
 975 system locale doesn't have the characters '&aacute;', '&scaron;' or '&ccaron;',
 976 they are converted to appropriate ascii characters.
 977
 978 <h2 id=exceptions>Exceptions</h2>
 979
 980 Because Ajla can parallelize or reorder function calls, exceptions as we know
 981 them from Java or C++ wouldn't be useful because they could be triggered at
 982 random points. Exceptions in Ajla are implemented differently. Exception is just
 983 a special value that can be stored in any variable.
 984 <br>
 985 <br>
 986 For example "<code>var x := 0 div 0;</code>" will store the "<i>invalid
 987 operation</i>" exception into the variable <code>x</code>.
 988 <br>
 989 <br>
 990 If we don't use the variable <code>x</code>, the exception is quietly discarded.
 991 <br>
 992 <br>
 993 If we perform arithmetic using the exception, the exception is propagated. For
 994 example, if we execute "<code>var y := x + 1;</code>", the variable
 995 <code>y</code> will hold the exception as well. There is one exception to this
 996 rule &mdash; the operators "<code>and</code>" and "<code>or</code>" don't always
 997 propagate exception if one of the arguments is known. "<code>false and
 998 exception</code>" or "<code>exception and false</code>" evaluates to
 999 "<code>false</code>". "<code>true or exception</code>" or "<code>exception or
1000 true</code>" evaluates as "<code>true</code>".
1001 <br>
1002 <br>
1003 If we attempt to perform a conditional branch that depends on the exception
1004 value, the current function is terminated and the exception is returned to the
1005 caller. For example "<code>if x = 3 then something;</code>" will terminate the
1006 current function.
1007 <br>
1008 <br>
1009 There's an operator "is_exception" that returns true if the argument is an
1010 exception and that returns false otherwise. It allows us to "handle" the
1011 exception. For example, we could write this code to report the exception to the
1012 user:
1013 <pre>
1014         if is_exception x then
1015                 write(h[1], "Exception occurred" + nl);
1016         else
1017                 write(h[1], "There's no exception, the value is " + ntos(x) + nl);
1018 </pre>
1019 Floating point "NaN" values are treated like exceptions &mdash;
1020 <code>is_exception</code> will return <code>true</code> if the value is a NaN.
1021 <br>
1022 <br>
1023 Every exception contains three values:
1024 <dl>
1025 <dt>Class
1026 <dd><code>ec_sync</code>, <code>ec_async</code>, <code>ec_syscall</code> or
1027 <code>ec_exit</code>
1028 <dl>
1029 <dt><code>ec_sync</code>
1030 <dd>The exception happened due to execution of the program. For example, invalid
1031 numeric calculation or index out of array/list size.
1032 <dt><code>ec_async</code>
1033 <dd>The exception happened due to conditions not related to the program. For
1034 example, memory allocation failure falls into this category.
1035 <dt><code>ec_syscall</code>
1036 <dd>The exception happened because some syscall failed.
1037 <dt><code>ec_exit</code>
1038 <dd>The exception holds the return value that should be returned when the
1039 program exits.
1040 </dl>
1041 <dt>Type
1042 <dd>This is an exception code. Exception types are listed in the file
1043 <code>stdlib/ex_codes.ajla</code> &mdash; see the constants
1044 "<code>error_*</code>".
1045 <dt>Code
1046 <dd>This is auxiliary value. It's meaning depends on the exception type.
1047 <dl>
1048 <dt>Type: <code>error_system</code>
1049 <dd>Code is one of the <code>system_error_*</code> values.
1050 <dt>Type: <code>error_errno</code>
1051 <dd>Code is the <code>errno</code> value.
1052 <dt>Type: <code>error_os2</code>
1053 <dd>Code is the OS/2 error number.
1054 <dt>Type: <code>error_os2_socket</code>
1055 <dd>Code is the OS/2 socket error number.
1056 <dt>Type: <code>error_win32</code>
1057 <dd>Code is the Windows error number.
1058 <dt>Type: <code>error_h_errno</code>
1059 <dd>Code is the <code>h_errno</code> error number.
1060 <dt>Type: <code>error_gai</code>
1061 <dd>Code is the <code>getaddrinfo</code> return value.
1062 <dt>Type: <code>error_subprocess</code>
1063 <dd>Code is the subprocess exit number, if the code is negative, it is the
1064 signal number that terminated the subprocess.
1065 <dt>Type: <code>error_exit</code>
1066 <dd>Code is the return value that should be returned from the current process.
1067 </dl>
1068 </dl>
1069 Note that because different systems (POSIX, OS/2, Windows) have different error
1070 codes, Ajla tries to translate common error codes to one of the
1071 <code>system_error_*</code> values. For example, a "file exists" error gets
1072 translated to <code>system_error_eexist</code>, so that the program that tests
1073 for it can be portable. However, not all error codes could be translated and if
1074 an unknown error code is received, it is reported as <code>error_errno</code>,
1075 <code>error_os2</code> or <code>error_win32</code> depending on the operating
1076 system.
1077 <br>
1078 <br>
1079 Additionally, exceptions may contain an optional error string and an optional
1080 stack trace, so that the user can determine where did the exception happen.
1081
1082 <h3>Operators that examine exceptions</h3>
1083 <dl>
1084 <dt><code>is_exception</code>
1085 <dd>Returns true if the argument is an exception.
1086 <dt><code>exception_class</code>
1087 <dd>Returns class of an exception.
1088 <dt><code>exception_type</code>
1089 <dd>Returns type of an exception.
1090 <dt><code>exception_aux</code>
1091 <dd>Returns auxiliary value of an exception.
1092 <dt><code>exception_string</code>
1093 <dd>Returns a string representing the type and aux values, you can use it to
1094 display the exception to the user.
1095 <dt><code>exception_payload</code>
1096 <dd>Returns the raw string attached to the exception.
1097 <dt><code>exception_stack</code>
1098 <dd>Returns the stack trace attached to the exception.
1099 </dl>
1100
1101 <h3>Function that manipulate exceptions</h3>
1102 The unit <code>exception</code> (located in the file
1103 <code>stdlib/exception.ajla</code>) contains the following functions:
1104 <dl>
1105 <dt><code>exception_make</code>
1106 <dd>Makes an exception with the given class, type and code and optional stack
1107 trace.
1108 <dt><code>exception_make_str</code>
1109 <dd>Makes an exception with the given class, type, code and string and optional
1110 stack trace.
1111 <dt><code>exception_copy</code>
1112 <dd>Copies the exception from a variable <code>s</code> that has a type
1113 <code>src_type</code> to the return value that has a type <code>dst_type</code>.
1114 The variable <code>s</code> must hold an exception, if not, <i>invalid
1115 operation</i> exception is returned.
1116 </dl>
1117
1118 <h3>Statements that manipulate exceptions</h3>
1119 <dl>
1120 <dt><code>eval expression</code>
1121 <dd>Evaluate a given expression (or more expressions separated by a comma), and
1122 discards the result. It may be used to print debugging messages, for example
1123 <code>eval debug("message")</code>. The <code>debug</code> statement writes the
1124 message to the standard error handle.
1125 <dt><code>xeval expression</code>
1126 <dd>Evaluate a given expression (or more expressions separated by a comma). If
1127 the result is non-exception, the result is discarded. If the result is an
1128 exception, the current function is terminated and the exception is returned as a
1129 return
1130 value.
1131 <dt><code>abort</code>
1132 <dd>Terminate the current function with with <code>ec_sync</code>,
1133 <code>error_abort</code>.
1134 <dt><code>abort expression</code>
1135 <dd>Evaluate a given expression (or more expressions separated by a comma). If
1136 the result is an exception, the current function is terminated and the exception
1137 is returned as a return value. If the result is non-exception, the current
1138 function exits with <code>ec_sync</code>, <code>error_abort</code>. It may be
1139 used with the statement "<code>internal</code>" to terminate the whole process
1140 if some internal error happens &mdash; <code>abort internal("this shouldn't
1141 happen")</code>.
1142 <dt><code>keep variables</code>
1143 <dd>Doesn't evaluate the variables, it just marks the variables as live, so
1144 that the optimizer won't discard them.
1145 </dl>
1146
1147 <h3>Syntax errors</h3>
1148 Note that syntax errors are also treated as exceptions &mdash; if the function
1149 with syntax error is never called, the error is ignored; if it is called, the
1150 exception is returned as a return value. In this program, we define a function
1151 "<code>syntax_error</code>" that contains a syntax error:
1152 <pre>
1153 fn syntax_error : int
1154 [
1155         bla bla bla;
1156 ]
1157
1158 fn main
1159 [
1160         var q := syntax_error;
1161         if is_exception q then [
1162                 write(h[1], "Exception happened" + nl);
1163         ]
1164 ]
1165 </pre>
1166 This program will write: "<code>Exception happened</code>".
1167 <br>
1168 <br>
1169 Reporting exceptions lazily when the function is called may not be useful during
1170 program development &mdash; when you are developing a program, it is recommended
1171 to use the "<code>--compile</code>" flag. It will attempt to compile all the
1172 functions in the program and it will report an error if any of them fails.
1173
1174 <h2 id=i_o>I/O</h2>
1175
1176 We have already seen the function <code>write</code> to perform an I/O. Let's
1177 have a look at other I/O functions. I/O functions take and return the value of
1178 type <code>world</code>, this ensures that they are properly sequenced and that
1179 they are not reordered or executed in parallel. I/O functions specify a handles
1180 on which the I/O is to be performed, <code>handle</code> represents a handle to
1181 a file (or pipe, character device, block device, socket). <code>dhandle</code>
1182 represents a handle to a directory. Handles are automatically closed when the
1183 handle variable is no longer referenced by the program.
1184 <br>
1185 <br>
1186 The function <code>main</code> receives a <code>dhandle</code> argument that is
1187 the handle to the current working directory and a list of <code>handle</code>
1188 values that represents the standard input, output and error streams.
1189 <br>
1190 <br>
1191 Handles may be manipulated in three modes:
1192 <dl>
1193 <dt>Read mode
1194 <dd>The handle is being read sequentially
1195 <dt>Write mode
1196 <dd>The handle is being written sequentially
1197 <dt>Block mode
1198 <dd>You can perform read and write operations on arbitrary offsets in the file.
1199 This mode only works for files and block devices.
1200 </dl>
1201 You shouldn't mix these modes on a single file because it may result in bugs
1202 &mdash; for example, some operating systems have the functions
1203 <code>pread</code> and <code>pwrite</code> and they use them when doing I/O on
1204 the handle in the block mode. However, other operations systems don't have these
1205 functions, so they will lock the file handle, perform <code>lseek</code>,
1206 perform <code>read</code> or <code>write</code> and unlock the file handle. If
1207 you mixed block mode with read mode, the read mode would read from invalid file
1208 offsets that were set up by the block mode.
1209 <br>
1210 <br>
1211 The I/O functions are defined in the unit <code>io</code>. This unit is
1212 automatically included in the main program. If you need I/O in other units, you
1213 must import the <code>io</code> unit explicitly.
1214 <dl>
1215 <dt><code>fn ropen(w : world, d : dhandle, f : bytes, flags : int) : (world,
1216 handle);</code>
1217 <dd>This function will open a file in a read mode and return a handle to the
1218 file. <code>w</code> is the world token, <code>d</code> is the base directory
1219 that is used for file name lookup, <code>f</code> is the file name,
1220 <code>flags</code> is one of the <code>open_flag_*</code> flags. For this
1221 function, only the flag <code>open_flag_no_follow</code> is allowed.
1222 <dt><code>fn read(w : world, h : handle, size : int) : (world, bytes);</code>
1223 <dd>Read the specified number of bytes from the handle. If end-of-file is
1224 detected, it returns less bytes. If not enough bytes is available (in case of a
1225 pipe or a character device), the function will sleep until the specified number
1226 of bytes is read.
1227 <dt><code>fn read_partial(w : world, h : handle, size : int) : (world,
1228 bytes);</code>
1229 <dd>Read the specified number of bytes from the handle. If not enough bytes are
1230 available, the function returns less bytes. If no bytes are available, the
1231 function sleeps until at least one byte is returned.
1232 <hr>
1233 <dt><code>fn wopen(w : world, d : dhandle, f : bytes, flags : int, mode : int) :
1234 (world, handle);</code>
1235 <dd>Opens a file in a write mode and return a handle to it. <code>flags</code>
1236 contain one or more of <code>open_flag_append</code>,
1237 <code>open_flag_create</code>, <code>open_flag_must_create</code>,
1238 <code>open_flag_no_follow</code>. <code>open_flag_append</code> specifies that
1239 we want to append to the file rather than overwrite it,
1240 <code>open_flag_create</code> specifies that we want to create the file if it
1241 doesn't exist, <code>open_flag_must_create</code> specifies that we want to fail
1242 with an error if the file exists, <code>open_flag_no_follow</code> suppresses
1243 the dereferencing of the last symlink in a file name. <code>mode</code>
1244 represents the permissions of the file if it is created, it may be
1245 <code>open_mode_ro_current_user</code>, <code>open_mode_ro_all_users</code>,
1246 <code>open_mode_rw_current_user</code>, <code>open_mode_read_all_users</code>,
1247 <code>open_mode_default</code> or other value.
1248 <dt><code>fn write(w : world, h : handle, s : bytes) : world;</code>
1249 <dd>Writes the bytes to the write handle.
1250 <dt><code>fn wcontiguous(w : world, h : handle, size : int64) : world;</code>
1251 <dd>Allocates a contiguous space for <code>size</code> bytes. Only some of the
1252 operating systems (Linux and OS/2) support preallocation of file data. If the
1253 operating system doesn't support it, the function returns with success and does
1254 nothing.
1255 <dt><code>fn pipe(w : world) : (world, handle, handle);</code>
1256 <dd>Creates a pipe and returns two handles. The first handle is used for reading
1257 from the pipe and the second handle is used for writing to the pipe.
1258 <hr>
1259 <dt><code>fn bopen(w : world, d : dhandle, f : bytes, flags : int, mode : int) :
1260 (world, handle);</code>
1261 <dd>Opens a file in a block mode. <code>flags</code> is a combination of
1262 <code>open_flag_*</code>. <code>mode</code> represents the permissions of the
1263 file if it is created.
1264 <dt><code>fn bread(w : world, h : handle, position : int64, size : int) :
1265 (world, bytes);</code>
1266 <dd>Read bytes from the specified position. If end-of-file is encountered, the
1267 function returns less bytes.
1268 <dt><code>fn bwrite(w : world, h : handle, position : int64, s : bytes) :
1269 world;</code>
1270 <dd>Write bytes to the specified position. If we write beyond file end, the file
1271 is extended.
1272 <dt><code>fn bsize(w : world, h : handle) : (world, int64);</code>
1273 <dd>Returns the size of the file.
1274 <dt><code>fn bdata(w : world, h : handle, off : int64) : (world, int64);</code>
1275 <dd>Skips over a hole in the file. Returns a next offset where some data are
1276 allocated. Some filesystems do not support holes; for them this function returns
1277 <code>off</code>.
1278 <dt><code>fn bhole(w : world, h : handle, off : int64) : (world, int64);</code>
1279 <dd>Skips over data in the file. Returns a next offset where there is a hole in
1280 the file. Some filesystems do not support holes; for them this function returns
1281 <dt><code>fn bsetsize(w : world, h : handle, size : int64) : world;</code>
1282 <dd>Truncates a file to the specified size or extends it.
1283 <dt><code>fn bcontiguous(w : world, h : handle, pos : int64, size : int64) :
1284 world;</code>
1285 <dd>Allocates a contiguous space at the specified offset. Some operating systems
1286 do not support file preallocation, for them, this function return success
1287 without doing anything.
1288 <dt><code>fn bclone(w : world, src_h : handle, src_pos : int64, dst_h : handle,
1289 dst_pos : int64, size : int64) : world;</code>
1290 <dd>Clones a byte range from <code>src_h</code> starting at <code>src_pos</code>
1291 to <code>dst_h</code> starting at <code>dst_pos</code>. Only some filesystems
1292 support cloning, if the filesystem doesn't support it, an error is reported.
1293 <hr>
1294 <dt><code>fn droot(w : world) : dhandle;</code>
1295 <dd>Returns a handle to the root directory. On Windows or OS/2, it returns a
1296 handle to <code>C:\</code>.
1297 <dt><code>fn dnone(w : world) : dhandle;</code>
1298 <dd>Returns an invalid directory handle. It is useful if you want to open a file
1299 and you know that the file path is absolute &mdash; in this case, you can pass
1300 <code>dnone()</code> to <code>ropen</code>, <code>wopen</code>,
1301 <code>bopen</code> or <code>dopen</code>.
1302 <dt><code>fn dopen(w : world, d : dhandle, f : bytes, flags : int) : (world,
1303 dhandle);</code>
1304 <dd>Open a directory that is relative to an existing directory. The only allowed
1305 flag is <code>open_flag_no_follow</code>.
1306 <dt><code>fn dread(w : world, d : dhandle) : (world, list(bytes));</code>
1307 <dd>Reads the directory and returns the list of directory entries.
1308 <dt><code>fn dpath(w : world, d : dhandle) : (world, bytes);</code>
1309 <dd>Returns a path that the directory points to. Note that we cannot return a
1310 path for file handles, because there may be multiple names referring to a single
1311 inode.
1312 <dt><code>fn dmonitor(w : world, d : dhandle) : (world, world);</code>
1313 <dd>Monitor the specified directory for changes. If the operating system doesn't
1314 support directory monitoring, exception is returned. If the operating system
1315 supports directory monitoring, the first value is returned immediately and the
1316 second value is returned when the directory changed.
1317 </dl>
1318 There are more functions that manipulate files and directories, see the file
1319 <code>stdlib/io.ajla</code>.
1320
1321 <h3>I/O error handling</h3>
1322 If some I/O operations fails, an exception is stored into the resulting
1323 <code>world</code>. If you attempt to perform more I/O with the world tag that
1324 is an exception, no I/O is performed, and the exception is returned back in the
1325 world tag. Consequently, you don't need to test for exception after every I/O
1326 operation &mdash; you can perform several I/O operations with no exception
1327 checking between them and check exceptions only once at the end of the sequence.
1328 If you attempt to write to a file and the array that is being written contains
1329 an exception, the data up to the exception is written and then the exception is
1330 returned.
1331 <br>
1332 <br>
1333 If you need to recover from the exception, you need to take a world value that
1334 existed before the exception happened and use it as a current world value
1335 &mdash; there's a function <code>recover_world</code> that does it.
1336 <br>
1337 <br>
1338 This is an example program that shows how exceptions could be recovered. It
1339 takes two arguments, coverts both of them to integer numbers, tries to divide
1340 them and writes the result.
1341 <pre>
1342 fn main
1343 [
1344         var old_w := w;
1345         var x1 := ston(args[0]);
1346         var x2 := ston(args[1]);
1347         write(h[1], ntos(x1) + " / " + ntos(x2) + " = " + ntos(x1 div x2) + nl);
1348         if is_exception w then [
1349                 var msg := exception_string w;
1350                 recover_world(old_w);
1351                 write(h[1], "An exception " + msg + " happened and was recovered" + nl);
1352         ]
1353 ]
1354 </pre>
1355 If the second argument is zero, you get this output "<code>1 / 0 = An exception
1356 Invalid operation happened and was recovered</code>". The <code>msg</code>
1357 variable will capture the exception message. Then, we recover the world tag, so
1358 that it points to an older value before the exception happened. As we recovered
1359 it, we can write to the standard output again.
1360 <br>
1361 <br>
1362 If you don't pass any arguments to this programs, you get "<code>An exception
1363 Index out of range happened and was recovered</code>" &mdash; here, the
1364 exception happens when we attempt to evaluate "<code>args[0]</code>" and
1365 "<code>args[1]</code>".
1366
1367 <h3>Lazy functions for I/O</h3>
1368 In <code>io.ajla</code> there are functions with <code>_lazy</code> suffix. They
1369 do not take world as an argument and do not return it. They are intended to be
1370 used in situations where the data accessed are not supposed to change during
1371 program execution. If the files and directories don't change, we don't need to
1372 sequence the I/O using the world variable.
1373 <br>
1374 <br>
1375 For example, the function <code>read_lazy</code> will read a handle and return a
1376 list of bytes, reading more data as they are needed. This program will read
1377 lines from standard input, echoing the lines back, and prints "<code>read all
1378 the lines, exiting...</code>" when the user terminates the input stream with
1379 Ctrl-D.
1380 <pre>
1381 fn main
1382 [
1383         var lines := list_break_to_lines(read_lazy(h[0]));
1384         for line in lines do [
1385                 write(h[1], "read a line: """ + line + """." + nl);
1386         ]
1387         write(h[1], "read all the lines, exiting..." + nl);
1388 ]
1389 </pre>
1390 The <code>list_break_to_lines</code> functions takes a list of bytes, breaks it
1391 to separate lines and returns list of lists of bytes representing the lines.
1392
1393 <h2 id=units>Units</h2>
1394
1395 Larger program can be broken up into multiple units. Unit starts with the
1396 "<code>unit</code>" keyword and the unit name (the unit name must match the file
1397 name), then, there's an interface section listing all public functions and
1398 types. Then there's the "<code>implementation</code>" keyword and then there are
1399 private functions and types and implementations of the public versions.
1400 <br>
1401 <br>
1402 The "<code>uses</code>" keyword will import a unit and make all public functions
1403 and types visible. You can import units from your program or from the standard
1404 library. The standard library is located in the directory "<code>stdlib</code>".
1405 Some of these units are declared with "<code>private unit</code>" keywords,
1406 these cannot be imported by your program, they can only be imported by other
1407 units in the standard library.
1408 <br>
1409 <br>
1410 Every Ajla source file automatically imports the unit "<code>system.ajla</code>.
1411 The main program source file also imports "<code>io.ajla</code>" and
1412 "<code>treemap.ajla</code>".
1413 <br>
1414 <br>
1415 Let's have look at the <a href="#fib">Fibonacci number calculation</a> and let's
1416 move the calculation to a separate unit. Now, we have a file
1417 "<code>fibunit.ajla</code>" with
1418 this content:
1419 <pre>
1420 unit fibunit;
1421
1422 fn fib(n : int) : int;
1423
1424 implementation
1425
1426 fn fib(n : int) : int
1427 [
1428         if n <= 1 then
1429                 return n;
1430         else
1431                 return fib(n - 2) + fib(n - 1);
1432 ]
1433 </pre>
1434 And a file "<code>fib.ajla</code>" with this content:
1435 <pre>
1436 uses fibunit;
1437
1438 fn main
1439 [
1440         var x := ston(args[0]);
1441         var f := fib(x);
1442         write(h[1], "fib " + ntos(x) + " = " + ntos(f) + nl);
1443 ]
1444 </pre>
1445 The interface section in the "<code>fibunit</code>" file specifies that the unit
1446 exports one function, "<code>fib</code>". The file "<code>fib.ajla</code>"
1447 imports the unit using the "<code>uses fibunit;</code>" statement.
1448 <br>
1449 <br>
1450 For larger programs, units may be located in different directories, when you
1451 import them, you use dot as a directory separator. For example "<code>uses
1452 ui.curses;</code>" imports the unit from the file
1453 "<code>stdlib/ui/curses.ajla</code>".
1454
1455 <h3>Name clashes</h3>
1456 If you declare a unit with a name that's already present in the standard
1457 library, your unit will take precedence and it will be imported instead of the
1458 unit in the standard library. However, if some file in the standard library
1459 imports a unit that's defined both in the standard library and in your program,
1460 the version from the standard library will be used.
1461 <br>
1462 <br>
1463 The same rule applies when function or type names clash. Your program will use a
1464 function that's declared in your program, however the standard library will use
1465 a version that's declared in the standard library.
1466 <br>
1467 <br>
1468 In new version of Ajla, the standard library can be extended with new units,
1469 functions and types. However, it shouldn't break existing programs because they
1470 will preferentially reference units, functions and types that are declared in
1471 them.
1472
1473 <h3>Hiding the implementations of types</h3>
1474 Just like you can hide function implementations in the implementation section,
1475 you can hide type implementations as well. For example, see the unit
1476 <code>heap</code> from the standard library (i.e. the file
1477 <code>stdlib/heap.ajla</code>). In the interface section, there's
1478 <pre>
1479 type heap(key : type, cls : class_ord(key));
1480 </pre>In the implementation section, there's
1481 <pre>
1482 type heap(key : type, cls : class_ord(key)) := list(key);
1483 </pre>
1484 When you import the unit using "<code>uses heap</code>", the compiler will read
1485 the statements up to the "<code>implementation</code>" keyword and then stop.
1486 The compiler will see that "<code>heap</code>" is a type that has one
1487 "<code>key</code>" parameter and one "<code>cls</code>" parameter, but it won't
1488 know how this type is defined. So, it will allow you to pass the variables with
1489 the "<code>heap</code>" type back and forth between functions, but it won't let
1490 you modify these variables directly.
1491 <br>
1492 <br>
1493 When the compiler will be parsing the <code>heap.ajla</code> file directly, it
1494 will process the line "<code>type heap(key : type, cls : class_ord(key)) :=
1495 list(key);</code>". From this point on, it knows that "<code>heap</code>" is
1496 implemented as a list and it will allow all list operations to be performed on
1497 the "<code>heap</code>" type.
1498 <br>
1499 <br>
1500 We can hide implementations of types from common code, so that the
1501 implementations may be changed without disrupting the program. For example, we
1502 could change the implementation of heap from a list to a binary tree and
1503 existing code could use the same interface functions.
1504
1505 <h2 id=type_classes>Type classes</h2>
1506
1507 Type classes allow us to write functions that can operate on different types.
1508 For example, let's have a look at this function that multiplies matrices
1509 containing double-precision numbers:
1510 <pre>
1511 fn matmult(const n : int, a b : array(real64, [n, n])) : array(real64, [n, n])
1512 [
1513         var result := array_fill(0., [n, n]);
1514         for i := 0 to n do
1515                 for j := 0 to n do
1516                         for k := 0 to n do
1517                                 result[i, j] += a[i, k] * b[k, j];
1518         return result;
1519 ]
1520 </pre>
1521 The variable <code>n</code> is the size of the matrices &mdash; note that if we
1522 want to use a variable in a type definition, we must declare it with a
1523 <code>const</code> specifier, so that the variable cannot be changed. If we
1524 changed <code>n</code>, it would no longer match the size of the arrays.
1525 <code>a</code> and <code>b</code> are two matrices &mdash; they are square
1526 arrays of <code>real64</code> with both dimensions equal to <code>n</code>. The
1527 function return another square array of <code>real64</code>.
1528 <br>
1529 <br>
1530 What if we want to multiply matrices containing single-precision numbers? We
1531 could copy the code and replace <code>real64</code> with <code>real32</code>,
1532 but copying code is considered antipattern. Or, we can use type classes:
1533 <pre>
1534 fn matmult~inline(t : type, implicit cls : class_unit_ring(t), const n : int,
1535                   a b : array(t, [n, n])) : array(t, [n, n])
1536 [
1537         var result := array_fill(cls.zero, [n, n]);
1538         for i := 0 to n do
1539                 for j := 0 to n do
1540                         for k := 0 to n do
1541                                 result[i, j] += a[i, k] * b[k, j];
1542         return result;
1543 ]
1544 </pre>
1545 In this second example, we can see new arguments. The <code>t</code> argument
1546 represents a type. The <code>cls</code> argument represents operations that can
1547 be done on the type <code>t</code>. We need to perform addition and
1548 multiplication on the type <code>t</code>, so we use the "unit ring" class that
1549 has these operations. The arguments <code>n</code>, <code>a</code> and
1550 <code>b</code> are similar to the previous example.
1551 <br>
1552 <br>
1553 Type class is a record that is parameterized by a type and that contains
1554 constants or function references. We can look at the standard library
1555 (<code>stdlib/system.ajla</code>) for the definition of
1556 <code>class_unit_ring</code>:
1557 <pre>
1558 record class_unit_ring(t : type) [
1559         add : fn(t, t) : t;
1560         zero : t;
1561         neg : fn(t) : t;
1562         subtract : fn(t, t) : t;
1563         multiply : fn(t, t) : t;
1564         one : t;
1565 ]
1566 </pre>
1567 The function <code>matmult</code> can accept any type for which
1568 <code>class_unit_ring</code> exists &mdash; it accepts floating-point numbers,
1569 integers, rational numbers and fixed-point numbers. You can declare
1570 <code>class_unit_ring</code> for your own type and then, you can pass this type
1571 to the function <code>matmult</code> as well. In order to improve performance,
1572 we should define the function <code>matmult</code> with "<code>~inline</code>".
1573 Without "<code>~inline</code>", the compiler would do indirect function call
1574 through the <code>class_unit_ring</code> record for every multiplication and
1575 addition.
1576 <br>
1577 <br>
1578 Note that if we pass less arguments than what was specified in the function
1579 prototype, Ajla attempts to infer the remaining arguments. So, you can write
1580 this:
1581 <pre>
1582         var m1 : array(real32, [ 10, 10 ]);
1583         var m2 : array(real32, [ 10, 10 ]);
1584         ... fill m1 and m2 with some data ...
1585         var m3 := matmult(m1, m2);
1586 </pre>
1587 The first argument (the type) is inferred from the type in the arguments
1588 <code>m1</code> and <code>m2</code>. The second argument (the class) is inferred
1589 from the standard library. The third argument (the dimension) is inferred from
1590 the dimensions of arguments <code>m1</code> and <code>m2</code>.
1591
1592 <h3>Standard type classes</h3>
1593 This diagram shows some of the default type classes defined in the standard
1594 library:
1595 <br>
1596 <br>
1597 <img src=classes.svg alt="Standard type classes in Ajla" width=100%>
1598 <br>
1599 <br>
1600 Magma, monoid, group, unit ring and division ring come from abstract algebra.
1601 Magma has one binary operation. Monoid has one binary operation and a zero
1602 element. Group is a monoid that has inverse element. Unit ring is a commutative
1603 group that has multiplication and a "1" element. Division ring is a unit ring
1604 that has a reciprocal.
1605 <br>
1606 <br>
1607 Real number class has additional mathematical functions, you can look at
1608 <code>class_real_number</code> in <code>stdlib/system.ajla</code> for the list
1609 of them. Integer number has operations that can be done on integers (see
1610 <code>class_integer_number</code>), fixed integer number has all the operation
1611 of integer number, and adds operations that can be only done on integers that
1612 have fixed size &mdash; <code>rol</code>, <code>ror</code>, <code>bswap</code>
1613 and <code>brev</code>.
1614 <br>
1615 <br>
1616 <code>class_eq</code> represents types for which equality is defined.
1617 <code>class_org</code> represents types where we can compare elements.
1618 <code>class_logical</code> represents types with the "<code>and</code>",
1619 "<code>or</code>", "<code>xor</code>" and "<code>not</code>" operations.
1620 <br>
1621 <br>
1622 For example, this is a prototype of the function <code>list_sort</code> that
1623 sorts a list:
1624 <br><code>fn list_sort(t : type, implicit c : class_ord(t), l : list(t)) :
1625 list(t);</code><br>
1626 It takes a type, an ordered class and a list of elements of type <code>t</code>.
1627 It returns the sorted list. Because we specified that the type has an ordered
1628 class, we can use comparison operators <code>=</code>, <code>&lt;&gt;</code>,
1629 <code>&lt;=</code>, <code>&gt;=</code> in the function body. If you need to sort
1630 a list with a custom comparison operation, you can define your own
1631 "<code>class_ord</code>" containing a pointer to your comparison functions and
1632 pass it as an argument to the "<code>list_sort</code>" function.
1633 <br>
1634 <br>
1635 Note that standard operators are defined using type classes. For example the
1636 multiplication operator is defined as "<code>operator * 2000 ~inline (t : type, c
1637 : class_unit_ring(t), val1 val2 : t) : t := c.multiply(val1, val2);</code>", so
1638 that we can use the operator on any type that has class_unit_ring defined.
1639
1640 <h2 id=threads>Threads</h2>
1641
1642 Ajla uses world-passing to sequence I/O. If we need to create more threads, we
1643 can split the variable "<code>w</code>" to more variables and the virtual
1644 machine will execute them concurrently.
1645 <br>
1646 <br>
1647 This is an example of a loop that prints numbers from 1 to 10 and waits one
1648 second between them:
1649 <pre>
1650 fn main
1651 [
1652         for i := 1 to 11 do [
1653                 w := sleep(w, 1000000);
1654                 w := write(w, h[1], ntos(i) + nl);
1655         ]
1656 ]
1657 </pre>
1658 Now, we convert this example to two loops that run concurrently:
1659 <pre>
1660 fn main
1661 [
1662         var w1, w2 := fork(w);
1663         for i := 1 to 11 do [
1664                 w1 := sleep(w1, 1000000);
1665                 w1 := write(w1, h[1], "thread 1: " + ntos(i) + nl);
1666         ]
1667         for i := 1 to 11 do [
1668                 w2 := sleep(w2, 1000000);
1669                 w2 := write(w2, h[1], "thread 2: " + ntos(i) + nl);
1670         ]
1671         w := join(w1, w2);
1672 ]
1673 </pre>
1674 The "<code>fork</code>" function takes a "<code>world</code>" argument and
1675 splits it into two world arguments &mdash; "<code>w1</code>" and
1676 "<code>w2</code>". The first loop will iterate from 1 to 10 and sequence the I/O
1677 using "<code>w1</code>" and the second loop will iterate from 1 to 10 and
1678 sequence the I/O using "<code>w2</code>". The "<code>join</code>" function takes
1679 two world arguments, evaluates them both, and if one of them is an exception,
1680 the exception is returned. If both of them are not exceptions, a valid
1681 "<code>world</code>" variable is returned. The output of this program is:
1682 <pre>
1683 thread 1: 1
1684 thread 2: 1
1685 thread 1: 2
1686 thread 2: 2
1687 thread 1: 3
1688 thread 2: 3
1689 thread 1: 4
1690 thread 2: 4
1691 thread 1: 5
1692 thread 2: 5
1693 thread 1: 6
1694 thread 2: 6
1695 thread 1: 7
1696 thread 2: 7
1697 thread 1: 8
1698 thread 2: 8
1699 thread 1: 9
1700 thread 2: 9
1701 thread 1: 10
1702 thread 2: 10
1703 </pre>
1704 What is happening here? The loops are not really run in parallel, they are
1705 executed sequentially &mdash; Ajla can't parallelize statements within a single
1706 function. The first "<code>sleep</code>" function is executed and it waits for 1
1707 second. But before it returns, two timer ticks elapse and, as we have seen in
1708 the <a href="#automatic_parallelization">automatic parallelization</a> section,
1709 the "<code>main</code>" function resumes execution and the "<code>w1</code>"
1710 variable is pointing to a thunk. Next, we execute the "<code>write</code>"
1711 function, but because the variable "<code>w1</code>" is not known yet, the
1712 "<code>write</code>" function blocks. After two timer ticks, we return back to
1713 the "<code>main</code>" function, and we go to second iteration of the first
1714 loop. "<code>w1</code>" now points to a thunk that references the
1715 "<code>write</code>" function and this thunk references the
1716 "<code>sleep</code>" function. In the second iteration, we do exactly the same
1717 steps as in the first iteration &mdash; and so on up to the tenth iteration: we
1718 have gone through the first loop without printing anything, just creating a
1719 chain of thunks.
1720 <br>
1721 The second loop is executed as the first loop &mdash; it generates a chain of
1722 thunks referring functions "<code>sleep</code>" and "<code>write</code>" without
1723 printing anything. Then, we go to the "<code>join</code>" function &mdash; it
1724 waits on "<code>w1</code>". As it waits longer than two timer ticks, it is
1725 parallelized too and the variable "<code>w</code>" will be pointing to a thunk
1726 that references the "<code>join</code>" function.
1727 <br>
1728 Now, "<code>w</code>" is returned from the "<code>main</code>" function and the
1729 virtual machine will attempt to evaluate it. The evaluation will force the
1730 execution of the "<code>sleep</code>" and "<code>wait</code>" functions,
1731 resulting in numbers being printed to the standard output.
1732 <br>
1733 <br>
1734 We can use the "<code>~spark</code>"
1735 <a href="#functions">specifier</a> to make sure that the functions are
1736 parallelized immediately and that they don't wait for two timer ticks before the
1737 parallelization starts. This makes this example execute faster:
1738 <pre>
1739 fn main
1740 [
1741         var w1, w2 := fork(w);
1742         for i := 1 to 11 do [
1743                 w1 := sleep~spark(w1, 1000000);
1744                 w1 := write~spark(w1, h[1], "thread 1: " + ntos(i) + nl);
1745         ]
1746         for i := 1 to 11 do [
1747                 w2 := sleep~spark(w2, 1000000);
1748                 w2 := write~spark(w2, h[1], "thread 2: " + ntos(i) + nl);
1749         ]
1750         w := join(w1, w2);
1751 ]
1752 </pre>
1753
1754 <h3>Infinite loops</h3>
1755 Beware of infinite loops:
1756 <pre>
1757 fn main
1758 [
1759         while true do [
1760                 w := write(w, h[1], "Hello World!" + nl);
1761         ]
1762         return w;
1763 ]
1764 </pre>
1765 This will not print anything, because the dead code elimination pass will remove
1766 the "<code>w</code>" variable as well as the function "<code>write</code>" that
1767 sets it because the variable can't be returned from the function. A proper way
1768 how to write it is to use a "<code>xeval w</code>" statement in an infinite
1769 loop, so that the loop is terminated if the "<code>write</code>" function fails:
1770 <pre>
1771 fn main
1772 [
1773         while true do [
1774                 w := write(w, h[1], "Hello World!" + nl);
1775                 xeval w;
1776         ]
1777         return w;
1778 ]
1779 </pre>
1780 Another possibility how to fix it is to test the "<code>w</code>" variable for
1781 exception in the loop condition.
1782 <pre>
1783 fn main
1784 [
1785         while not is_exception w do [
1786                 w := write(w, h[1], "Hello World!" + nl);
1787         ]
1788         return w;
1789 ]
1790 </pre>
1791 Note that the "<code>w</code>" variable may be omitted, as shown in the
1792 <a href="#hello_world">Hello World</a> section.
1793
1794 <h3>Other thread functions</h3>
1795 <dl>
1796 <dt><code>any</code>
1797 <dd>Start evaluating both values and wait until any of them becomes evaluated.
1798 Returns "<code>false</code>" if the first value is evaluated and
1799 "<code>true</code>" if the second value is evaluated. If both of them are
1800 evaluated, "<code>false</code>" is returned.
1801 <dt><code>any_list</code>
1802 <dd>Start evaluating all the values in the list and wait until any of the
1803 becomes evaluated. Returns the index of the first value that is evaluated.
1804 <dt><code>is_ready</code>
1805 <dd>Returns "<code>true</code>" if the value is evaluated.
1806 <dt><code>never</code>
1807 <dd>Blocks and never completes.
1808 <dt><code>atomic_enter</code>
1809 <dd>Increases the atomic count &mdash; when the atomic count is non-zero, the
1810 thread will not be killed.
1811 <dt><code>atomic_exit</code>
1812 <dd>Decreases the atomic count &mdash; when the atomic count is zero, the thread
1813 may be killed if its return value is not used.
1814 </dl>
1815
1816 <h3>Message queues</h3>
1817 We can use message queues to communicate between threads. They are defined in
1818 the file "<code>stdlib/msgqueue.ajla</code>".
1819 <dl>
1820 <dt><code>msgqueue_new</code>
1821 <dd>Creates a new message queue holding entries of the specified type.
1822 <dt><code>msgqueue_send</code>
1823 <dd>Sends a message to the message queue. Every message has a tag and a value.
1824 The tag may be used to filter messages on the receive side.
1825 <dt><code>msgqueue_replace</code>
1826 <dd>Replace the content of the queue with a given message.
1827 <dt><code>msgqueue_receive</code>
1828 <dd>Waits until the queue is non-empty and returns the first message.
1829 <dt><code>msgqueue_receive_tag</code>
1830 <dd>Waits until the queue has at least one message with a given tag and returns
1831 this message.
1832 <dt><code>msgqueue_receive_nonblock</code>
1833 <dd>If the queue is non-empty, return the first message, otherwise return the
1834 exception "<code>error_not_found</code>".
1835 <dt><code>msgqueue_receive_tag_nonblock</code>
1836 <dd>If the queue contains a message with the specified tag, return it, otherwise
1837 return the exception "<code>error_not_found</code>".
1838 <dt><code>msgqueue_peek_nonblock</code>
1839 <dd>Return a message without removing it from the queue. If the queue is empty,
1840 the exception "<code>error_not_found</code>" is returned.
1841 <dt><code>msgqueue_peek_tag_nonblock</code>
1842 <dd>Return a message with the specified tag without removing it from the queue.
1843 If there is no such message, the exception "<code>error_not_found</code>" is
1844 returned.
1845 <dt><code>msgqueue_wait</code>
1846 <dd>Wait until the queue becomes non-empty.
1847 <dt><code>msgqueue_is_nonempty</code>
1848 <dd>Returns true if the queue is non-empty.
1849 <dt><code>msgqueue_any</code>
1850 <dd>Wait until any of the two message queues becomes non-empty.
1851 </dl>
1852 Note that there is one gotcha when using message queues &mdash; when you insert
1853 a record containing a message queue to the message queue itself, the message
1854 queue will leak. Ajla uses reference counts to track memory and in this
1855 situation, there will be circular reference dependence that prevents the message
1856 queue from being freed. The memory leak will be detected and resolved when Ajla
1857 exits, however while it is running, there is no way how to detect it and free
1858 the leaked message queue.
1859 <br>
1860 <br>
1861 This is an example program that uses a message queue to read characters from the
1862 keyboard:
1863 <pre>
1864 uses ui.termcap;
1865 uses ui.event;
1866
1867 fn main
1868 [
1869         var tc := termcap_init(d, env);
1870         var loc := locale_console_init(env);
1871         var q := msgqueue_new(event);
1872         var kbd_thread := event_get_keyboard(h[0], tc, loc, q);
1873         while not is_exception w do [
1874                 var tag, e := msgqueue_receive(q);
1875                 if e is keyboard then [
1876                         write(h[1], "keyboard event " + ntos(e.keyboard.key) + ", " + ntos(e.keyboard.flags) + nl);
1877                         if e.keyboard.key = 'q' then break;
1878                 ]
1879                 keep kbd_thread;
1880         ]
1881 ]
1882 </pre>
1883 <dl>
1884 <dt><code>var tc := termcap_init(d, env);</code>
1885 <dd>Initialize the termcap database and store it to the variable
1886 "<code>tc</code>".
1887 <dt><code>var loc := locale_console_init(env);</code>
1888 <dd>Initialize the locale according to environment variables.
1889 <dt><code>var q := msgqueue_new(event);</code>
1890 <dd>Create a message queue of events. "<code>event</code>" is defined in the
1891 file "<code>stdlib/ui/event.ajla</code>".
1892 <dt><code>var kbd_thread := event_get_keyboard(h[0], tc, loc, q);</code>
1893 <dd>Create a thread that reads the keyboard from handle 0. "<code>tc</code>" is
1894 the termcap database, "<code>loc</code>" is the current locale and
1895 "<code>q</code>" is the message queue, where events will be sent.
1896 <dt><code>while not is_exception w do</code>
1897 <dd>Loop while there is no exception.
1898 <dt><code>var tag, e := msgqueue_receive(q);</code>
1899 <dd>Read the message queue; wait if it is empty.
1900 <dt><code>if e is keyboard then</code>
1901 <dd>If the event is a keyboard event, take this branch.
1902 <dt><code>write(h[1], "keyboard event " + ntos(e.keyboard.key) + ", " +
1903 ntos(e.keyboard.flags) + nl);</code>
1904 <dd>Print the keyboard event.
1905 <dt><code>if e.keyboard.key = 'q' then break;</code>
1906 <dd>Exit if the user pressed 'q'.
1907 <Dt><code>keep kbd_thread;</code>
1908 <dd>This statement prevents the optimizer from removing the thread. Without this
1909 statement, the optimizer would conclude that the variable
1910 "<code>kbd_thread</code>" is not used anymore, it would free it and that would
1911 terminate the "<code>event_get_keyboard</code>" thread.
1912 </dl>
1913
1914 <h2 id=ffi>FFI</h2>
1915
1916 FFI (foreign function interface) allows us to call functions that are defined in
1917 some of the system libraries. It is the only unsafe part of Ajla &mdash; it
1918 cannot be memory-safe because C pointers aren't safe as well. FFI only works if
1919 the library "<code>libffi</code>" was present when Ajla was compiled. If not,
1920 the FFI functions return the exception "<code>error_not_supported</code>".
1921 <br>
1922 <br>
1923 This is an example program that uses FFI to print the string "Hello World!" to
1924 the standard output, using the "<code>write</code>" function imported from the
1925 standard library.
1926 <pre>
1927 uses ffi;
1928
1929 fn main
1930 [
1931         var str := "Hello World!" + nl;
1932         var destr := ffi_destructor_new();
1933         var message := ffi_destructor_allocate(destr, len(str), 1, false);
1934         ffi_poke_array(message, str);
1935         var wrt := ffi_create_function("", "write", ffi_error.e_errno, 3,
1936                 ffi_type.t_ssize, [ffi_type.t_sint, ffi_type.t_pointer, ffi_type.t_usize ]);
1937         var xh := ffi_handle_to_number(destr, h[1]);
1938         var r, e := ffi_call_function(wrt, [ xh, message, len(str) ]);
1939         ffi_destructor_destroy(destr);
1940         if r = -1 then [
1941                 write(h[2], "error " + ntos(e) + " occurred" + nl);
1942                 exit(1);
1943         ] else if r &lt;&gt; len(str) then [
1944                 write(h[2], "wrote only " + ntos(r) + " bytes" + nl);
1945                 exit(1);
1946         ]
1947 ]
1948 </pre>
1949 Ajla functions may be terminated any time, so in order to reliably free memory,
1950 the FFI interface introduces so-called destructors. The destructor may contain
1951 function calls and/or file handles and/or allocated memory. When the destructor
1952 variable is freed, the stored calls are performed and then the allocated memory
1953 is freed and the associated file handles are closed (if no one else refers to
1954 them).
1955 <dl>
1956 <dt><code>var str := "Hello World!" + nl;</code>
1957 <dd>The string to be written.
1958 <dt><code>var destr := ffi_destructor_new();</code>
1959 <dd>This line allocates a destructor. So far, it is empty, so no operation is
1960 done when the destructor is freed.
1961 <dt><code>var message := ffi_destructor_allocate(destr, len(str), 1,
1962 false);</code>
1963 <dd>This line allocates memory from the destructor and returns a pointer to the
1964 allocated memory. <code>len(str)</code> is the size of the allocated memory,
1965 <code>1</code> is the alignment of the memory, <code>false</code> specifies that
1966 the memory doesn't have to be cleared. When the <code>destr</code> variable is
1967 freed, the allocated memory is automatically freed as well.
1968 <dt><code>ffi_poke_array(message, str);</code>
1969 <dd>This copies the string to the pointer returned by the previous function.
1970 Note that the function <code>ffi_poke_array</code> may be used to overwrite
1971 arbitrary memory in the process.
1972 <dt><code>var wrt := ffi_create_function("", "write", ffi_error.e_errno, 3,
1973 ffi_type.t_ssize, [ffi_type.t_sint, ffi_type.t_pointer, ffi_type.t_usize
1974 ]);</code>
1975 <dd>This statement loads a pointer to the function "<code>write</code>" from the
1976 standard library. The first argument is a library name (empty string for libc),
1977 the second argument is the name of the function, the third argument specifies
1978 that we are interested in the <code>errno</code> value returned by the function,
1979 the fourth argument is the number of fixed arguments, the fifth argument is the
1980 return type, the sixth argument is the list containing types for the three
1981 arguments &mdash; the first argument has type signed integer, the second
1982 argument has type pointer, the third argument has type unsigned size_t.
1983 <dt><code>var xh := ffi_handle_to_number(destr, h[1]);</code>
1984 <dd>This statement converts an Ajla handle to a system handle. The result will
1985 be "1" because we are writing to the standard output. A reference to the handle
1986 is stored in the destructor, so that it will be dropped when the destructor is
1987 dropped.
1988 <dt><code>var r, e := ffi_call_function(wrt, [ xh, message, len(str)
1989 ]);</code>
1990 <dd>Call the "<code>write</code>" function, <code>r</code> is the return value,
1991 <code>e</code> is the <code>errno</code> value.
1992 <dt><code>ffi_destructor_destroy(destr);</code>
1993 <dd>This function indicates that the <code>destr</code> variable should be freed
1994 at this point. If we didn't use <code>ffi_destructor_destroy(destr)</code>, the
1995 <code>destr</code> variable would be freed when it goes out of scope (i.e. after
1996 the call to <code>ffi_handle_to_number</code>) and the function
1997 <code>ffi_call_function</code> would access invalid memory and invalid handle.
1998 <dt>if r = -1 then ...
1999 <dd>The rest of the program prints an error if the write failed.
2000 </dl>
2001
2002 <h2 id=performance_considerations>Performance considerations</h2>
2003
2004 Ajla uses both interpreter and machine code generator when running the program.
2005 The interpreter handles all the constructs of the language and the machine code
2006 generator handles only the common constructs. For example, if we add two
2007 integers, it is translated to the instruction "add" followed by the instruction
2008 "jo" that jumps to the interpreter on overflow. The interpreter will perform the
2009 overflowed operation on long integers using the gmp library.
2010 <br>
2011 <br>
2012 In order to get decent performance, you must make sure that the hot spot of the
2013 program is running in the machine code and not in the interpreter. You shouldn't
2014 use long integers, lazy evaluation, exceptions, sparse lists, infinite lists in
2015 the hot spot, because these constructs cause escape from the machine code to the
2016 interpreter. There are functions "<code>list_flatten</code>" and
2017 "<code>array_flatten</code>" that convert sparse list or array to a flat
2018 structure &mdash; you can use these functions before the hot spot to make sure
2019 that the hot spot can access the array without escaping to the interpreter.
2020 <br>
2021 <br>
2022 There are following profiling parameters:
2023 <dl>
2024 <dt><code>--profile=function</code>
2025 <dd>It will count how many times each function is called and the time spent in
2026 the function and it will display the functions sorted by the time.
2027 <dt><code>--profile=escape</code>
2028 <dd>It will show locations where escape from the machine code to the interpreter
2029 happened. It shows the function, the line number, the number of escapes and the
2030 opcode that triggered the escape.
2031 <dt><code>--profile=memory</code>
2032 <dd>It will show where memory was allocated.
2033 <dt><code>--profile</code>
2034 <dd>Enable "function", "escape" and "memory".
2035 </dl>
2036 If you enable "<code>--debug=leak</code>", Ajla will maintain a list of all
2037 memory blocks that are allocated. You can dump this list at various points in
2038 your program to see where is it allocating most memory. You can use:
2039 <dl>
2040 <dt><code>eval report_memory_summary("hello");</code>
2041 <dd>Report the summary of allocated memory, for example "<code>DEBUG MESSAGE:
2042 allocated memory at hello: 689030 / 4054 = 169</code>".
2043 <dt><code>eval report_memory_most("hello");</code>
2044 <dd>Report locations where most memory was allocated, for example this
2045 "<code>DEBUG MESSAGE: pcode.c:3298 284314 / 234 = 1215</code>" means that
2046 there is 284314 bytes in 234 blocks allocated at pcode.c:3298.
2047 <dt><code>eval report_memory_largest("hello");</code>
2048 <dd>Report the largest allocated blocks, for example this <code>"DEBUG MESSAGE:
2049 pcode.c:3298 35378"</code> means that there is a block of 35378 bytes being
2050 allocated at pcode.c:3298.
2051 </dl>
2052
2053 <h2>Other options</h2>
2054 <dl>
2055 <dt><code>--compile</code>
2056 <dd>Compile the whole program without running it. It is useful if you need to
2057 check the source code for syntax errors. Without this switch, the program is
2058 being compiled as it runs and syntax errors in unused parts of the program are
2059 not reported.
2060 <dt><code>--nosave</code>
2061 <dd>Do not save and load compiled code. This option also inhibits saving and
2062 loading cache of functions with the <code>~save</code> specifier.
2063 <dt><code>--ptrcomp</code>
2064 <dd>Use pointer compression &mdash; pointers will have only 32 bits and the
2065 maximum allocatable memory is 32GiB. It reduces memory consumption slightly.
2066 <dt><code>--strict-calls</code>
2067 <dd>Turn off auto-parallelization. It is useful if you want to get longer stack
2068 trace for debugging purposes. Normally, the stack trace is chopped at a point
2069 where auto-parallelization happens.
2070 <dt><code>--system-malloc</code>
2071 <dd>Use system malloc instead of Ajla malloc. It reduces memory consumption, and
2072 it decreases performance slightly.
2073 <dt><code>--thread-tick</code>
2074 <dd>Use a thread for timer ticks instead of using a signal.
2075 <dt><code>--threads=<i>n</i></code>
2076 <dd>Use the specified number of threads. By default, Ajla detects the number of
2077 hardware threads in the system and uses this value.
2078 <dt><code>--tick=<i>n</i></code>
2079 <dd>The timer tick in microseconds. By default, it is 10000. If you specify too
2080 small value, you should enable <code>--thread-tick</code> as well. If the tick
2081 value is smaller that the time it takes to process a signal, the signal would be
2082 hammering the worker threads so heavily, that they can't make any progress.
2083 </dl>
2084
2085 <h2 id=hacking_ajla>Hacking Ajla</h2>
2086
2087 <h3>Configure options</h3>
2088 <dl>
2089 <dt><code>--enable-threads=pthread</code>
2090 <dd>Compile with pthreads (default, if pthreads are detected).
2091 <dt><code>--enable-threads=win32</code>
2092 <dd>Compile with Windows threads.
2093 <dt><code>--disable-threads</code>
2094 <dd>Compile without threads.
2095 <dt><code>--disable-computed-goto</code>
2096 <dd>Don't use computed goto. By default, computed goto is used if the compiler
2097 supports it.
2098 <dt><code>--enable-bitwise-frame</code>
2099 <dd>Use bitwise tags on the stack rather than byte tags. It may or may not
2100 improve performance depending on the actual workload. By default, bitwise tags
2101 are disabled, because they perform slightly worse.
2102 <dt><code>--enable-debuglevel=0</code>
2103 <dd>No debugging at all.
2104 <dt><code>--enable-debuglevel=1</code>
2105 <dd>Default option. This enables debugging assertions in
2106 non-performance-critical parts of the code. It also enables
2107 "<code>--debug</code>" command line flags that turn on debugging of various
2108 subsystems of Ajla.
2109 <dt><code>--enable-debuglevel=2</code>
2110 <dd>This enables all debugging assertions even in performance-critical parts of
2111 the code.
2112 <dt><code>--enable-debuglevel=3</code>
2113 <dd>This enables all debugging checks that degrade performance seriously.
2114 </dl>
2115 If you need fine-grained control of debugging, you can modify the file
2116 "<code>debug.h</code>".
2117
2118 <h3>Debugging options</h3>
2119 If you configured Ajla with "<code>--enable-debuglevel=1</code>",
2120 "<code>--enable-debuglevel=2</code>" or "<code>--enable-debuglevel=3</code>",
2121 the following options are available:
2122 <dl>
2123 <dt><code>--debug=magic</code>
2124 <dd>Put a magic value at the start every memory block. The magic value is
2125 verified when reallocating or freeing the block. If there is a mismatch,
2126 internal error is reported and the core is dumped.
2127 <dt><code>--debug=redzone</code>
2128 <dd>Put a redzone value at the end of every memory block and verify it when
2129 reallocating or freeing the block.
2130 <dt><code>--debug=fill</code>
2131 <dd>Fill the allocated and freed blocks with a byte pattern.
2132 <dt><code>--debug=leak</code>
2133 <dd>Maintain a list of allocated blocks and test for memory leaks when Ajla
2134 exits. It will display a file and line of the allocation that leaked.
2135 <dt><code>--debug=memory</code>
2136 <dd>Enable "magic, redzone, fill, leak".
2137 <dt><code>--debug=mutex-errorcheck</code>
2138 <dd>Set the pthread attribute PTHREAD_MUTEX_ERRORCHECK on mutexes.
2139 <dt><code>--debug=mutex</code>
2140 <dd>Check the correct usage of mutexes. Also, enable
2141 "<code>mutex-errorcheck</code>".
2142 <dt><code>--debug=cond</code>
2143 <dd>Check the correct usage of condition variables.
2144 <dt><code>--debug=thread</code>
2145 <dd>Check the correct usage of threads.
2146 <dt><code>--debug=tls</code>
2147 <dd>Check the correct usage of thread-local storage.
2148 <dt><code>--debug=handles</code>
2149 <dd>Check the correct usage of handles.
2150 <dt><code>--debug=objects</code>
2151 <dd>Enable "mutex-errorcheck, mutex, cond, thread, tls, handles".
2152 <dt><code>--debug</code>
2153 <dd>Enable all debugging options.
2154 </dl>
2155
2156 <h3>Rebuilding the standard library</h3>
2157 The standard library and the compiler source code is located in the directories
2158 "<code>stdlib</code>" and "<code>newlib</code>". These directories have
2159 identical content. The file "<code>builtin.pcd</code>" contains compiled
2160 standard library and the compiler itself.
2161 <br>
2162 <br>
2163 You shouldn't modify the content of the directory "<code>stdlib</code>" because
2164 the directory would not match the file "<code>builtin.pcd</code>" and it would
2165 result in crashes.
2166 <br>
2167 <br>
2168 If you need to modify the standard library, you should modify files in the
2169 directory "<code>newlib</code>" and then run the script
2170 "<code>./scripts/update.sh</code>" or "<code>./scripts/update.sh all</code>"
2171 &mdash; this will rebuild "<code>builtin.pcd</code>" and then copy the content
2172 of "<code>newlib</code>" to "<code>stdlib</code>" to make sure that it matches
2173 newly generated "<code>builtin.pcd</code>".
2174 </body>
2175 </html>
2176
2177
2178 <!--
2179 vim: textwidth=80
2180 >