Loko Scheme ¶

1.1 Scheme ¶

Scheme is a dialect of the Lisp programming language invented by Guy Lewis Steele Jr. and Gerald Jay Sussman in the mid 1970s. The first Lisp language was LISP, which was created by John McCarthy in the second half of the 1950s.

Lisp’s syntax uses S-expressions, which were created by McCarthy to represent LISP functions as data in his eval function (published in 1960). Eval is a one-page universal LISP function capable of running any other LISP function. The first LISP interpreter was created when Steve Russell compiled the eval function by hand.

Today many languages offer a large subset of the features of Lisp, and some attempt to offer those of Scheme as well. S-expressions are not added because it would turn those languages into Lisps.

Distinctive features of Lisp languages are dynamic typing, garbage collection, and S-expressions (“symbolic expressions”). Scheme adds some additional distinctive features on top of those: static scoping, proper tail-recursion, hygienic macros, full continuations and dynamic-wind.

• Dynamic typing means that the programmer does not need to prove to the compiler that a program is well-typed. This is beneficial because there are true statements about programs that are impossible to prove except by running the programs.
• Garbage collection is the automatic reclamation of unused memory. This is beneficial because there are programs that are impossible to write without it.
• S-expressions provide a convenient means to represent code as data, in a format that the Lisp programmer is used to working with, which enables automatic transformations via macros and dynamic evaluation through eval. This is beneficial because there are programs that are impossible to write without dynamic code evaluation. It also relieves the programmer of having to guess how the parser will pick apart the code.
• Static scoping means that variable usage is connected with the binding of the variable as it appears in the text of the program. This is standard in most languages today, but Scheme is one of the few languages that gets this consistently right. (Dynamic scoping is available if needed through dynamic-wind, because there are some programs that cannot be written without it).
• Proper tail-recursion provides a guarantee that when a procedure call appears in a tail context (such as in the final expression of a procedure) no extra stack frame is used. This is beneficial because there are programs that cannot be written without proper tail-recursion.
• Hygienic macros means that a library can provide extensions to the Scheme syntax that are indistinguishable from built-in Scheme syntax, and hygiene means that these macros do not accidentally break static scoping. Less powerful macro systems are prone to the insertion of variables that conflict with those already used in the programs.
• (Continuations are usually explained in hopelessly abstract terms, so I will be very concrete here). Continuations are copies of the stack and the state associated with dynamic-wind. Many languages provide a way to escape upwards in the stack (e.g. longjmp or exceptions), but continuations also lets programs restore the stack to what it looked like when the continuation was captured. Imagine throwing an exception, thereby going up the stack, and then having the exception handler fix the problem and then go back down the stack to resume. Scheme is also unusual in that it lets continuations be reinstated multiple times. Continuations are useful because there are programs that cannot be written without them. Any control structure can be expressed with them, even those not built in to the language.
• Dynamic-wind provides a means to run code when a part of the program is entered and then when it is exited. Continuations means that it can happen multiple times. This feature is useful because there are programs that cannot be written without it.

The features described above can be simulated in languages that lack them. Tail-recursion can be implemented manually by simulating a stack with a list, dynamic typing can be implemented with an abstract data type and type dispatching, garbage collection can be implemented for a data structure, and continuations can be implemented manually with continuation-passing style.

Such simulations are always possible in the sense that any Turing-complete language can implement any other Turing-complete language. But these simulations will not exist on the same level as the host language and are therefore of an inferior nature.

1.2 Scheme standards ¶

Scheme is standardized through two different types of documents. The first are called the Revisedⁿ Reports on the Algorithmic Language Scheme (RⁿRS). R⁵RS came out in 1998 and was followed by R⁶RS in 2007. R⁵RS was also followed by R⁷RS, which came out in 2013. Both of them are successors to R⁵RS.

The second type of documents are called Scheme Requests For Implementation (SRFI). This is a community-driven process whereby new language features can be developed and suggested for implementations to use. Many of them are mostly portable code, while other ones require adaptions to each Scheme implementation that wants to support them.

1.3 Where Loko fits in ¶

Scheme has many implementations. Every known way to implement a programming language has probably been tried with Scheme. There are Scheme implementations for basically all operating systems and all types of machines. There have even been Scheme CPUs. Some say there are more implementations than applications. And Loko Scheme is one of those implementations.

Every Scheme implementation has something that makes it unique. This is what is peculiar about Loko:

• Loko runs on bare metal (and on top regular Unix kernels).
• Loko builds statically linked binaries.
• Loko is written in only Scheme and a small amount of assembly.
• Loko’s ABI is incompatible with C and does not use it on any level.
• Loko’s runtime uses concurrency based on Concurrent ML.
• Loko supports both R⁶RS and R⁷RS libraries and programs.
• Loko provides the safety guarantees of R⁶RS even for R⁷RS code.
• Loko uses the hardware for free type checking (branchless car, etc).

Due to some of the above, Loko Scheme is not suitable for every use case. There are plenty of other Scheme implementations available if Loko Scheme cannot work for your application.

2.1 Building Loko ¶

Download a release tarball from https://scheme.fail or clone the git repository: git clone https://scheme.fail/git/loko.git/. Release tarballs, git commits and tags are signed with the OpenPGP key 0xE33E61A2E9B8C3A2.

The release tarball has everything needed for building Loko Scheme from GNU/Linux. It comes with the required Akku packages and a pre-built binary.

• (Optional if you have the release tarball).

  Loko Scheme needs an R6RS Scheme implementation for bootstrapping. It can currently be bootstrapped with Chez Scheme.

  Install Chez Scheme, version 9.5 or later, as a bootstrap compiler.

• (Optional if you have the release tarball, but highly recommended and required for the samples).

  Install the package manager Akku.scm, version 1.0.0 or later.

• Run make to compile Loko. GNU make is required.
• Install with make install.
• (Optional) Build and install the manual with make install-info.

The binaries tend toward being reproducible. There are some minor differences between the results from Chez Scheme and Loko Scheme due to different gensym implementations. This is fixable.

If you’re building from Git and pull in updates, then it will at certain points be necessary to rebootstrap. This can be done with make rebootstrap, but it’s a bit impractical at the moment due to the number of commits that require a rebootstrap. A simpler way is to remove the loko-prebuilt binary and bootstrap again from Chez Scheme (but that’s cheating).

• Cross-compiling
• Loko from a distribution

2.2 Running ¶

Loko Scheme runs either under an existing operating system kernel (currently Linux and NetBSD), under a hardware virtual machine or directly on bare hardware.

• Running under Linux or NetBSD
• Running under KVM (QEMU)
• Running on bare metal
• Running in Docker

#!/usr/bin/env scheme-script
(import (rnrs))
(display "Hello, world!\n")

qemu-system-x86_64 -enable-kvm -kernel loko -m 1024 -serial stdio

2.3 Compiling a program ¶

Loko can compile R6RS top-level programs:

loko --compile hello.sps

The above will compile the R6RS top-level program hello.sps and create the binary hello, which will run on Linux and bare metal.

To compile an R7RS program:

loko -std=r7rs --compile hello.sps

Libraries are looked up from the LOKO_LIBRARY_PATH environment variable (which is automatically set by the package manager Akku). The use of eval is disabled by default to speed up builds, but can be enabled with -feval:

loko -feval --compile hello.sps

The supported targets can be changed with -ftarget=TARGET. The default target is pc+linux. Other targets are linux for Linux only, netbsd for NetBSD only and pc for only bare metal.

An additional weird target is provided. It is called polyglot and creates binaries that run on Linux, NetBSD and bare metal. This is even less useful than it seems and may be removed in the future.

You can also omit the normal Scheme libraries. If you use -ffreestanding then only the assembler based runtime is added on top of the libraries that your program uses. This is useful mostly when you’re working on the compiler. The source distribution has an example where this is used, samples/hello/just-hello.sps.

You can tune the parameters for the source-level optimizer (cp0). The argument -fcp0-size-limit=N sets the size limit and -fcp0-effort-limit=N sets the effort limit.

The command line is very inflexible, so try to stick to the fixed argument order for now.

Loko integrates its run-time into the resulting binary and Loko’s source code needs to be available for compilation to succeed. The location is decided by PREFIX when compiling Loko, but can be overridden using the LOKO_SOURCE environment variable.

3.1 Standard libraries ¶

The standard R6RS Scheme libraries are provided. Please see the documents on the website for the official versions. Unofficial versions of R6RS updated with errata are also available online.

The standard R7RS-small libraries are provided as well. They are not available by default in the REPL and need to be imported with e.g. (import (scheme base)).

• SRFI implementations

3.2 Base library ¶

The (loko) library is automatically loaded into the repl. It provides all exports from the R6RS libraries, SRFI 98, and the exports shown below. It is intended as a convenient starting point for the repl user and a place to put features that are expected from a Scheme implementation, but that do not belong to any other library.

Procedure: interaction-environment ¶

Procedure: load filename ¶

Procedure: include filename ¶

Include code into the program from filename, as if it had been written in the place of the include form.

Procedure: void ¶

Returns a void object.

The value that came from nowhere. Even though it has never been standardized, it is customary for Scheme implementations to use void for (if #f #f), (values) and the value of set! and other mutating operations.

In Loko Scheme, void objects carry a copy of the program counter.

(list (void))
⇒ (#<void #x21731F>)

Parameter: library-directories ¶

This parameter is a list of strings that name directories to check when importing libraries.

Default: (".")

Parameter: library-extensions ¶

This parameter is a list of strings with file extensions to use when importing libraries.

Default: (".loko.sls" ".sls" ".ss" ".scm")

Procedure: installed-libraries ¶

For use in the repl. Returns a list of libraries.

Procedure: uninstall-library name ¶

For use in the repl. Uninstalls the name library.

Prrocedure: environment-symbols env ¶

The list of symbols defined in the environment env.

Procedure: expand expr ¶

Expands the expression, returning core forms. The format of the returned forms should not be relied on.

Procedure: expand/optimize expr ¶

Expands and optimizes the expression, returning core forms. The format of the returned forms should not be relied on.

Parameter: cp0-size-limit ¶

Limits how much the source-level optimizer cp0 will allow the code to grow.

Default: 16

Parameter: cp0-effort-limit ¶

Limits the effort spent by the source-level optimizer cp0.

Default: 50

Procedure: disassemble procedure ¶

Print the disassembly of procedure. It is annotated with labels for local jump destinations and some simple code equivalents.

> (disassemble car)
Disassembly for #<procedure car loko/libs/pairs.loko.sls:3224>

  entry:
   206E00 83F8F8       (cmp eax #xFFFFFFF8)
   206E03 0F8505000000 (jnz L0)
 ; (set! rax (car rdi))
   206E09 488B47FE     (mov rax (mem64+ rdi #x-2))
   206E0D C3           (ret)
  L0:
   206E0E E96DA2FFFF   (jmp (+ rip #x-5D93))

Procedure: machine-type ¶

The machine type that Loko is running on. This is a vector where the first element is the CPU type amd64 and the second is the system environment (linux, netbsd or pc).

Syntax: time expr ¶

Run the procedure thunk once with no arguments and print some numbers of memory allocation and elapsed time.

Procedure: time-it what thunk ¶

This is the procedural version of time.

Procedure: time-it* what iterations thunk ¶

Run thunk repeatedly iterations times and print some bogus statistics. The aim is that this procedure should be the best way to do micro benchmarks.

Please note that iterations is rounded upwards to some multiple close to the time stamp counter resolution. This procedure is not meant to be used for long-running procedures, the typical case is something that takes at most a few dozen cycles, at most a few thousand.

The code under test should also be compiled ahead of time for the results to reflect more than the interpreter’s overhead. In the example below, code is not compiled.

> (time-it* "fx+" 10000000 (lambda () (fx+ x 1)))
Timing fx+ to find the minimum cycle time:
New minimum is 1819 cycles with 10000000 iterations to go.
...
New minimum is 234 cycles with 6257346 iterations to go.

  The cycle count varied between 234 and 83160784
  (Arithmetic mean)      µ  = 248.75
  (Standard deviation)   σ  = 24.33
  (Population variance)  σ² = 592.08
                    min x_i = µ-.61σ
  Used 9736890 samples (263110 outliers discarded).
234
> (time-it* "+" 10000000 (lambda () (+ x 1)))
Timing + to find the minimum cycle time:
New minimum is 1751 cycles with 10000000 iterations to go.
...
New minimum is 240 cycles with 9968540 iterations to go.

  The cycle count varied between 240 and 84141254
  (Arithmetic mean)      µ  = 252.96
  (Standard deviation)   σ  = 30.46
  (Population variance)  σ² = 927.82
                    min x_i = µ-.43σ
  Used 9979862 samples (20138 outliers discarded).
240

Note that cp0 will optimize the thunk before it runs, so you may end up benchmarking something other than what you thought. Check with expand/optimize. If the code is entered in the REPL then you also measure the overhead of eval.

Modern computers are notoriously difficult to get any consistent results from. An improvement in cycles could be because the code slightly moved in memory. See Producing Wrong Data Without Doing Anything Obviously Wrong (2009, Mytkowicz, et al). A more lively view of the problem is the presentation Performance Matters (2019, Emery Berger at Strange Loop).

Procedure: open-output-string ¶

Make a new string output port that accumulates characters in memory. The accumulated string can be extracted with get-output-string.

Procedure: get-output-string string-output-port ¶

Extract the accumulated string in string-output-port and reset it. Returns the string.

Procedure: port-file-descriptor port ¶

Get the file descriptor associated with port. Returns #f if there is no associated file descriptor.

Procedure: port-file-descriptor-set! port fd ¶

Set the file descriptor associated with port to fd.

This procedure is primarily intended to allow custom ports to have file descriptors. It is unspecified whether changing a port’s file descriptor affects the file descriptor used for subsequent operations on the port.

Procedure: gensym ¶

Generate an uninterned symbol. These are symbols which are not eq? to any other symbol.

Procedure: make-parameter default-value [fender] ¶

Create a new parameter object. Parameters are typically used to implement dynamically scoped variables together with parameterize. A parameter’s current value can be queried by calling it with no arguments and its value can be modified by calling it with one argument, the new value.

The optional fender procedure is applied to the value whenever the parameter is modified. The return value of fender is used in place of the new value. A typical use of this procedure is to do some type checks on the new value.

Syntax: parameterize ((name value) …) body… ¶

Parameterize rebinds the parameter name to value for the dynamic extent of body. This means that while body is running, name will be set to value. The value is possibly filtered by a fender procedure.

Whenever the program leaves the body, either by a normal return or a non-local exit (such as in a guard expression or by calling a continuation created by call/cc), the value is reset to the value it has outside of the body. If control reenters body, as in a call to a continuation created inside the body, the parameter will return to the value established by parameterize.

Although it has the same name, this syntax is a faster variant that is not fully compatible with SRFI-39. This variant is very common in Scheme implementations and matches the one used in e.g. Chez Scheme.

Procedure: loko-version ¶

The version number of the Loko Scheme runtime. This is a SemVer number and may include build information in the future.

Procedure: putenv name value ¶

Set the environment variable name to value. The name is always string.

If the value is a string then the variable is set to that value.

If the value is #f then the variable is removed.

This updates the environment used by SRFI 98 and can also be expected to be visible to any child processes started after the call.

The strings must not contain any #\nul characters. The name must not contain a #\= character. These limitations are not checked.

The names and values are always transcoded to/from UTF-8 in the POSIX interfaces.

Please beware that other Scheme implementations commonly leak memory through this procedure.

Procedure: collections ¶

The number of garbage collections.

Syntax: module [name] (exports …) body … ¶

Define a module. A module is like a library, but it uses an syntax which does not exist in any RnRS standards. It can also appear inside a library and is commonly used to hide internal definitions.

It is better to not use this syntax in your own code because it makes your code non-portable. It is provided for compatibility with other Scheme implementations.

Procedure: load-program filename ¶

Load and run the R6RS program filename.

Procedure: pretty-print obj [port] ¶

Writes obj to port using a write-compatible notation. Extra spaces and newlines are inserted to make the output more readable to a human.

3.3 Apropos ¶

The (loko apropos) library exports procedures for looking up symbols in environments.

Procedure: apropos-list name [env] ¶

Search the names of the environment env and all loaded libraries for symbols containing the substring name, which can be a string or a symbol.

If env is omitted then the default is to use the interaction environment.

The returned list contains entries of these formats:

• (library symbol) – this means that library exports the symbol. The library is loaded, but it may need to be imported.
• symbol – this means that symbol is available in env.

This procedure should be compatible with the similarly named one in Chez Scheme.

Procedure: apropos name [env] ¶

This is an analogue of the apropos-list procedure that is meant for interactive use.

3.4 Fibers ¶

The (loko system fibers) library exports procedures for fibers. Fibers are a form of lightweight concurrency based on Concurrent ML. For an overview, see Concurrency.

Procedure: spawn-fiber thunk ¶

Create a new fiber that will start running the procedure thunk, which takes no arguments.

Procedure: make-channel ¶

Create a new channel. Channels are places where two fibers can rendezvous to exchange a message. There is no buffering in a channel.

Procedure: channel? obj ¶

True if obj is a channel.

Procedure: put-message channel obj ¶

Put the message obj on the channel channel. Blocks until another fiber picks up the message. Returns unspecified values.

Procedure: get-message channel ¶

Get a message from the channel channel. Blocks until another fiber has arrived with a message. Returns the message.

Procedure: sleep time ¶

Block the fiber for time seconds.

Procedure: put-operation channel obj ¶

Returns an operation object that represents putting the message obj on the channel channel.

Procedure: get-operation channel ¶

Returns an operation object that represents getting a message from the channel channel.

Procedure: wrap-operation op f ¶

Returns an operation object that is the same as the operation op, except that the values a wrapped by the procedure f.

Procedure: sleep-operation seconds ¶

Returns an operation object that represents waiting until seconds have passed from the time of the call to this procedure.

Procedure: timer-operation a ¶

Return an operation object that represents waiting until absolute time a (in internal time units).

Procedure: choice-operation op … ¶

Returns an operation object that represents a choice between the given operations op …. If multiple operations can be performed then one is selected non-deterministically.

It is not an error to call this procedure with no arguments. It is in fact a useful construction when gathering operations.

If wrap-operation is used on a choice operation then every operation will be wrapped.

Procedure: perform-operation op ¶

Perform the operation op, possibly blocking the fiber until the operation is ready.

With choice-operation and perform-operation it’s possible to write code that waits for one of several operations. This can be something simple like waiting for a message with a timeout:

(perform-operation (get-operation ch) (sleep-operation 1))

This example will wait for a message on the channel ch for up to one second. In order to distinguish between a message and a timeout, wrap-operation is used:

(perform-operation
 (choice-operation
  (wrap-operation (get-operation ch) (lambda (x) (cons 'msg x)))
  (wrap-operation (sleep-operation 1) (lambda _ 'timeout))))

This code will either return (msg . x) where x is the received message; but if more than one second passes without a message it returns timeout.

The object returned from choice-operation can be returned from a procedure, stored in a data structure, sent over a channel, etc.

Procedure: make-cvar ¶

Make a new condition variable (in Concurrent ML’s terminology). These allow a program to wait for a condition to be signalled. See the procedures below.

Procedure: cvar? obj ¶

True if obj is a condition variable.

Procedure: signal-cvar! cvar ¶

Signal the condition variable cvar, unblocking any fibers that are waiting for it.

Procedure: wait cvar ¶

Wait for the condition variable cvar to be signalled, blocking until it is.

Procedure: wait-operation cvar ¶

Return an operation that represents waiting for the condition variable cvar to be signalled.

Procedure: yield-current-task ¶

Yield the current task and and let another fiber run. This is generally not needed in I/O-bound programs, but is provided to let CPU-bound programs cooperate and voluntarily let other fibers run.

Procedure: exit-current-task ¶

Stops the running fiber.

Procedure: run-fibers init-thunk ¶

Provided for compatibility with Guile. It runs the procedure init-thunk in the fibers scheduler. This procedure can return earlier in Loko than in does in Guile. Guile provides it because fibers are not an integrated feature in its runtime, so it needs an entry point for when to start and stop the fibers facility.

3.5 Unsafe procedures ¶

The (loko system unsafe) library provides raw access to kernel services, linear memory and I/O bus registers.

Procedure: syscall n arg … ¶

Calls the kernel’s system call number n with the arguments arg …. Returns a fixnum.

Example fork on Linux amd64:

(when (zero? (syscall 57))     ; __NR_fork
  (display "child process\n")
  (exit))                      ; child become a zombie

Scheme programs should generally not be written directly with syscalls any less than C programs would do the same. There are usually interactions with the standard library that should be considered, such as flushing of ports to prevent duplicated output.

Procedure: bytevector-address bytevector ¶

Get the linear address of the first byte of bytevector.

The first byte is guaranteed to have an alignment of eight bytes.

A moving garbage collector is used for bytevectors created with make-bytevector. There is no way to ensure that they do not move during GC, so their addresses should not be used to perform bus-mastering DMA.

Returns a fixnum.

Procedure: get-mem-u8 addr ¶

Procedure: get-mem-u16 addr ¶

Procedure: get-mem-u32 addr ¶

Procedure: get-mem-s61 addr ¶

Read a u8, u16, u32 or s61, respectively, from linear address addr and return it as a fixnum.

• If addr is unaligned then an exception is raised.
• On targets where fixnums are not wide enough to hold the result, a bignum will be used instead, but the bus access will be the correct width.
• Calls to these procedures will not be optimized away or reordered by the compiler.
• Each call corresponds to one memory read instruction of the matching size. For the signed 61-bit procedure this only applies to targets that can issue 64-bit memory bus operations.
• These calls may be issued out of order by the processor or go to the cache. This is usually only a problem when the memory area is backed by RAM. On AMD64 it is safe to read memory-mapped hardware registers with these procedures thanks to MTRR. Other situations may require locking instructions or memory barriers.

Procedure: put-mem-u8 addr n ¶

Procedure: put-mem-u16 addr n ¶

Procedure: put-mem-u32 addr n ¶

Procedure: put-mem-s61 addr n ¶

Write n as a u8, u16, u32 or s61, respectively, to linear address addr.

• If addr is unaligned then an exception is raised.
• Calls to these procedures will not be optimized away or reordered by the compiler.
• Each call corresponds to one memory write instruction of the matching size. For the signed 61-bit procedure this only applies to targets that can issue 64-bit memory bus operations.
• These calls may be issued out of order or be merged by the processor. This is usually only a problem when the memory area is backed by RAM. On AMD64 it is safe to read memory-mapped hardware registers with these procedures thanks to MTRR. Other situations may require locking instructions, manual flushes or memory barriers.

Returns unspecified values.

Procedure: get-i/o-u8 busaddr ¶

Procedure: get-i/o-u16 busaddr ¶

Procedure: get-i/o-u32 busaddr ¶

Read a u8, u16 or u32, respectively, from I/O bus address busaddr and return it as a fixnum.

The get-i/o-u32 procedure may return a bignum on targets where (<= (fixnum-width) 32), but the bus access will be 32-bit.

Procedure: put-i/o-u8 busaddr n ¶

Procedure: put-i/o-u16 busaddr n ¶

Procedure: put-i/o-u32 busaddr n ¶

Write n as a u8, u16 or u32, respectively, to I/O bus address busaddr.

Returns unspecified values.

Procedure: get-i/o-u8-n! busaddr addr n ¶

Procedure: get-i/o-u16-n! busaddr addr n ¶

Procedure: get-i/o-u32-n! busaddr addr n ¶

Read n units of u8, u16 or u32, respectively, from I/O bus address busaddr and write them to memory starting at linear address addr.

The address addr must be naturally aligned to the size of the writes. Otherwise an &assertion is raised.

Returns unspecified values.

Procedure: put-i/o-u8-n busaddr addr n ¶

Procedure: put-i/o-u16-n busaddr addr n ¶

Procedure: put-i/o-u32-n busaddr addr n ¶

Write n units of u8, u16 or u32, respectively, to I/O bus address busaddr while reading them from memory starting at linear address addr.

The address addr must be naturally aligned to the size of the reads. Otherwise an &assertion is raised.

Returns unspecified values.

3.6 Target libraries ¶

The following Linux-specific libraries are provided. Their usage mirrors 1:1 the functionality in the Linux manpages, section 2.

• (loko arch amd64 linux-numbers) – constants used in the Linux syscall interface (UAPI).
• (loko arch amd64 linux-syscalls) – thin wrappers around Linux syscalls.
• (loko arch amd64 netbsd-numbers) – constants used in the NetBSD syscall interface.
• (loko arch amd64 netbsd-syscalls) – thin wrappers around NetBSD/amd64 syscalls.

4.1 Tools support ¶

This section describes some tools can be used together with Loko Scheme when things go wrong.

• Disassembly
• Debugging
• Debug logs
• Profiling
• Memory checking
• Fuzzing

The condition has 5 components:
 1. &assertion &violation &serious
 2. &who: apply
 3. &message: "Tried to call a non-procedural object"
 4. &irritants: (#f)
 5. &program-counter: #x309795
End of condition components.

5.1 Loko Scheme website ¶

The Loko Scheme website has official release tarballs and an online copy of the manual.

5.2 Online communities ¶

There are two chat channels available on IRC. They are on the IRC network Libera.Chat and they are #scheme and #loko. The #scheme channel is for the whole Scheme community. You will need an IRC client to join these channels.

If you’re more of a forum or mailing list user, then there aren’t any direct options like this yet. But we have Usenet, which has filled this need even since before there was an Internet. The community-wide Scheme group is called ‘comp.lang.scheme’. It is accessible via any Usenet provider, even free ones like Eternal September. It is also accessible via one of the big search engine companies.

There is also a community-wide Scheme Wiki at http://community.schemewiki.org.

Another resource that has popped up recently is Discord. There is a Scheme Discord.

5.3 Issue tracker ¶

There may be an issue tracker at GitLab, but please instead use channels where issues nobody cares about can be lost in the mists of time. You can send bug reports to bugs@scheme.fail.

5.4 Package repositories ¶

There are repositories of packages online where you can find many useful libraries that work with Loko:

• Akku.scm – an R6RS/R7RS package manager. Akku also translates R7RS libraries to R6RS to try and make them work with R6RS implementations.
• Snow – an R7RS package manager. These packages (or snowballs) are also included in Akku’s repository.

6.1 Concurrency ¶

The concurrency in Loko exists at two different levels:

• Loko processes, which are preemptible processes running at the same privilege level and in the same page table as the Loko runtime.
• Loko fibers, which are lightweight processes that run inside a Loko process. They are an implementation of Concurrent ML.

When Loko starts it immediately sets up a Loko process for the scheduler (also called pid 0). The boot loader has already created a heap and stack for it. The scheduler is responsible for starting pid 1, handling interrupts, managing preemption, message passing between processes and other maintenance tasks. The first scheduler that starts is also responsible for booting all other processors in the system.

Currently all other processors boot up but stop after initialization. Some work needs to be done to allocate new scheduler processes for them.

Apart from the scheduler and Loko processes with fibers there are also normal usermode processes with their own page tables. This is where you can put all your FORTRAN and C programs.

Fibers are a lightweight concurrency system based on Concurrent ML. The implementation is heavily inspired by a Andy Wingo’s articles Growing Fibers. and A New Concurrent ML. Concurrent ML forms a fundamental principle for concurrency that can be used to implement higher-level concurrency like Go channels or Erlang processes.

For details on how to use fibers in your program, see Fibers. You can also consult the Guile fibers manual to some extent; it has a lot of background information.

The implementation in Loko is different from Guile fibers in these ways:

• Loko fibers need the import (loko system fibers) rather than (fibers).
• Loko fibers are based on pure call/cc to switch between fibers and the fiber scheduler. This is mostly because the Loko runtime doesn’t have delimited continuations, but it made it easier to quickly get the correct semantics for parameters.
• However, basing the implementation on call/cc brings a space leak. It means that there is some extra overhead from lugging around the unused parts of the continuation and the dynamic winders. In some programs, this state can potentially grow without bound. This could be solved without implementing delimited continuations, but extra support from the runtime is needed either way.
• Loko fibers are not preemptively scheduled. This is because of several reasons, explained in the next section. This means that you shouldn’t run long-running computations in a fiber that shares a Loko process with other fibers that need to be responsive (unless you explicitly yield the fiber every now and then).
• Loko fibers in a process do not run in parallel; they are not shared between processors. The way memory allocation is done in Loko means that two processors can’t manage the same heap.

XXX: The implementation described above has a broken dynamic-wind. See issue #26 in the bug tracker.

The API is compatible with Guile fibers, so the concurrency parts of a program written for Guile fibers should work with Loko fibers. The largest exception is Guile’s (fibers internals) library, which manages fiber schedulers. Loko only has one of those per Loko process. Another difference is that I/O is non-blocking by default on Loko.

A large part of what makes fibers attractive is that code can be written as if it were non-concurrent. You’re free to read and write to pipes and network streams without explicitly dealing with polling for when data is available or when file descriptors are ready for writing. One of the sample programs is a tiny web-server that spawns a fiber per connected client.

Loko on Linux takes care to set O_NONBLOCK on file descriptors and suspends the current fiber when syscalls return EAGAIN (also called EWOULDBLOCK). Loko uses epoll to find out when the file descriptor will be ready.

But Linux does not implement EAGAIN for regular files, so reading from a file can block. When this happens it prevents other fibers from running. Standard I/O is non-blocking, but other programs that use the same terminal can either get confused by that and/or turn it off. Even memory accesses can be blocking on Linux because pages can be swapped out to disk. (Turning off swap is not a good idea). The binary for your program was mmap’d by Linux when it got started and unmodified pages can be read back from disk, so Linux can freely evict the pages from memory. So having anything like a guaranteed responsive program on Linux is challenging. If anything goes wrong with the disk, all your processes can end up in uninterruptible sleep.

Loko on bare hardware has no operations that block other fibers from running.

• Why fibers are not preemptible
• Loko processes

6.2 Drivers ¶

A driver is a piece of code that allows for abstract access to a hardware device. In Loko Scheme they are collected in the drivers directory.

• Driver abstractions
• Hardware access
• Future directions for drivers

(define (driver·pci·uhci dev controller)
  ;; The UHCI registers are mapped to the location in BAR4
  (let ((bar (vector-ref (pcidev-BARs dev) 4)))
    ;; Disable keyboard and mouse legacy support
    (pci-put-u16 dev #xC0 #x0000)
    (driver·uhci (if (pcibar-i/o? bar) 'i/o 'mem)
                 (pcibar-base bar)
                 (pcibar-size bar)
                 (pcidev-irq dev)
                 controller)))

(define (driver·uhci reg-type reg-base reg-size irq controller)
  ;; Access to the device registers (independent of i/o vs mem)
  (define (reg-u8-ref offset)
    (assert (fx<? -1 offset reg-size))
    (case reg-type
      ((i/o) (get-i/o-u8 (fx+ reg-base offset)))
      ((mem) (get-mem-u8 (fx+ reg-base offset)))
      (else (assert #f))))
  ...)

(let ((driver·uhci
       (eval `(lambda (controller)
                (driver-source·uhci ,reg-type ,reg-base
                                    ,reg-size ,irq
                                    controller))
             (apply environment driver-environment·uhci))))
  (driver·uhci controller))

6.3 Interrupt handling ¶

Loko in essence treats device drivers as communicating sequential processes. IRQs from devices are treated as primitive messages from the device to the driver. Requests to configure the device or transfer data between the device and the rest of the system is also done with messages. Device drivers are not fundamentally different from other Scheme programs.

• Historical background
• An experimental approach to IRQs
• Loko’s use of traps
• Interrupts on bare hardware AMD64
• Interrupts on Linux AMD64