Clone this wiki locally
This manual is for Fibers (version 0.4.0, updated 16 December 2016)
Copyright 2016 Andy Wingo
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|• Introduction:||What’s this all about?|
|• Reference:||API reference.|
|• Pitfalls:||Stay on the happy path.|
|• Examples:||Starting points for a hack.|
|• Status:||Fibers is a work in progress.|
Fibers is a facility for lightweight concurrency in Guile.
|• Context:||How do other systems handle concurrency?|
|• Design:||Fibers’ point in the design space.|
1.1 A brief history of language facilities for concurrency
Modern machines have the raw capability to serve hundreds of thousands of simultaneous long-lived connections, but it’s often hard to manage this at the software level. Fibers tries to solve this problem in a nice way. Before discussing the approach taken in Fibers, it’s worth spending some time on history to see how we got here.
One of the most dominant patterns for concurrency these days is
“callbacks”, notably in the Twisted library for Python and the
callback approach to concurrency is that the efficient way to handle
tens of thousands of connections at once is with low-level operating
system facilities like
epoll. You add all of
the file descriptors that you are interested in to a “poll set” and
then ask the operating system which ones are readable or writable, as
appropriate. Once the operating system says “yes, file descriptor
7145 is readable”, you can do something with that socket; but what?
With callbacks, the answer is “call a user-supplied closure”: a
callback, representing the continuation of the computation on that
Building a network service with a callback-oriented concurrency system means breaking the program into little chunks that can run without blocking. Whereever a program could block, instead of just continuing the program, you register a callback. Unfortunately this requirement permeates the program, from top to bottom: you always pay the mental cost of inverting your program’s control flow by turning it into callbacks, and you always incur run-time cost of closure creation, even when the particular I/O could proceed without blocking. It’s a somewhat galling requirement, given that this contortion is required of the programmer, but could be done by the compiler. We Schemers demand better abstractions than manual, obligatory continuation-passing-style conversion.
Callback-based systems also encourage unstructured concurrency, as in practice callbacks are not the only path for data and control flow in a system: usually there is mutable global state as well. Without strong patterns and conventions, callback-based systems often exhibit bugs caused by concurrent reads and writes to global state.
Some of the problems of callbacks can be mitigated by using “promises” or other library-level abstractions; if you’re a Haskell person, you can think of this as lifting all possibly-blocking operations into a monad. If you’re not a Haskeller, that’s cool, neither am I! But if your typey spidey senses are tingling, it’s for good reason: with promises, your whole program has to be transformed to return promises-for-values instead of values anywhere it would block.
An obvious solution to the control-flow problem of callbacks is to use threads. In the most generic sense, a thread is a language feature which denotes an independent computation. Threads are created by other threads, but fork off and run independently instead of returning to their caller. In a system with threads, there is implicitly a scheduler somewhere that multiplexes the threads so that when one suspends, another can run.
In practice, the concept of threads is often conflated with a particular implementation, kernel threads. Kernel threads are very low-level abstractions that are provided by the operating system. The nice thing about kernel threads is that they can use any CPU that is the kernel knows about. That’s an important factor in today’s computing landscape, where Moore’s law seems to be giving us more cores instead of more gigahertz.
However, as a building block for a highly concurrent system, kernel threads have a few important problems.
One is that kernel threads simply aren’t designed to be allocated in huge numbers, and instead are more optimized to run in a one-per-CPU-core fashion. Their memory usage is relatively high for what should be a lightweight abstraction: some 10 kilobytes at least and often some megabytes, in the form of the thread’s stack. There are ongoing efforts to reduce this for some systems but we cannot expect wide deployment in the next 5 years, if ever. Even in the best case, a hundred thousand kernel threads will take at least a gigabyte of memory, which seems a bit excessive for book-keeping overhead.
Kernel threads can be a bit irritating to schedule, too: when one thread suspends, it’s for a reason, and it can be that user-space knows a good next thread that should run. However because kernel threads are scheduled in the kernel, it’s rarely possible for the kernel to make informed decisions. There are some “user-mode scheduling” facilities that are in development for some systems, but again only for some systems.
The other significant problem is that building non-crashy systems on top of kernel threads is hard to do, not to mention “correct” systems. It’s an embarrassing situation. For one thing, the low-level synchronization primitives that are typically provided with kernel threads, mutexes and condition variables, are not composable. Also, as with callback-oriented concurrency, one thread can silently corrupt another via unstructured mutation of shared state. It’s worse with kernel threads, though: a kernel thread can be interrupted at any point, not just at I/O. And though callback-oriented systems can theoretically operate on multiple CPUs at once, in practice they don’t. This restriction is sometimes touted as a benefit by proponents of callback-oriented systems, because in such a system, the callback invocations have a single, sequential order. With multiple CPUs, this is not the case, as multiple threads can run at the same time, in parallel.
Kernel threads can work. The Java virtual machine does at least manage to prevent low-level memory corruption and to do so with high performance, but still, even Java-based systems that aim for maximum concurrency avoid using a thread per connection because threads use too much memory.
In this context it’s no wonder that there’s a third strain of concurrency: shared-nothing message-passing systems like Erlang. Erlang isolates each thread (called processes in the Erlang world), giving each it its own heap and “mailbox”. Processes can spawn other processes, and the concurrency primitive is message-passing. A process that tries receive a message from an empty mailbox will “block”, from its perspective. In the meantime the system will run other processes. Message sends never block, oddly; instead, sending to a process with many messages pending makes it more likely that Erlang will pre-empt the sending process. It’s a strange tradeoff, but it makes sense when you realize that Erlang was designed for network transparency: the same message send/receive interface can be used to send messages to processes on remote machines as well.
No network is truly transparent, however. At the most basic level, the performance of network sends should be much slower than local sends. Whereas a message sent to a remote process has to be written out byte-by-byte over the network, there is no need to copy immutable data within the same address space. The complexity of a remote message send is O(n) in the size of the message, whereas a local immutable send is O(1). This suggests that hiding the different complexities behind one operator is the wrong thing to do. And indeed, given byte read and write operators over sockets, it’s possible to implement remote message send and receive as a process that serializes and parses messages between a channel and a byte sink or source. In this way we get cheap local channels, and network shims are under the programmer’s control. This is the approach that the Go language takes, and is the one we use in Fibers.
Structuring a concurrent program as separate threads that communicate over channels is an old idea that goes back to Tony Hoare’s work on “Communicating Sequential Processes” (CSP). CSP is an elegant tower of mathematical abstraction whose layers form a pattern language for building concurrent systems that you can still reason about. Interestingly, it does so without any concept of time at all, instead representing a thread’s behavior as a trace of instantaneous events. Threads themselves are like functions that unfold over the possible events to produce the actual event trace seen at run-time.
This view of events as instantaneous happenings extends to communication as well. In CSP, one communication between two threads is modelled as an instantaneous event, partitioning the traces of the two threads into “before” and “after” segments.
Practically speaking, this has ramifications in the Go language, which was heavily inspired by CSP. You might think that a channel is just a an asynchronous queue that blocks when writing to a full queue, or when reading from an empty queue. That’s a bit closer to the Erlang conception of how things should work, though as we mentioned, Erlang simply slows down writes to full mailboxes rather than blocking them entirely. However, that’s not what Go and other systems in the CSP family do; sending a message on a channel will block until there is a receiver available, and vice versa. The threads are said to “rendezvous” at the event.
Unbuffered channels have the interesting property that you can
select between sending a message on channel a or channel
b, and in the end only one message will be sent; nothing happens
until there is a receiver ready to take the message. In this way
messages are really owned by threads and never by the channels
themselves. You can of course add buffering if you like, simply by
making a thread that waits on either sends or receives on a channel,
and which buffers sends and makes them available to receives. It’s
also possible to add explicit support for buffered channels, as Go
does, which can reduce the number of context switches as there is no
explicit buffer thread.
Whether to buffer or not to buffer is a tricky choice. It’s possible
to implement singly-buffered channels in a system like Erlang via an
explicit send/acknowlege protocol, though it seems difficult to
implement completely unbuffered channels. As we mentioned, it’s
possible to add buffering to an unbuffered system by the introduction
of explicit buffer threads. In the end though in Fibers we follow
CSP’s lead so that we can implement the nice
that we mentioned above.
As a final point,
select is OK but is not a great language
abstraction. Say you call a function and it returns some kind of
asynchronous result which you then have to
select on. It could
return this result as a channel, and that would be fine: you can add
that channel to the other channels in your
select set and you
are good. However, what if what the function does is receive a
message on a channel, then do something with the message? In that
case the function should return a channel, plus a continuation (as a
closure or something). If
select results in a message being
received over that channel, then we call the continuation on the
message. Fine. But, what if the function itself wanted to
select over some channels? It could return multiple channels
and continuations, but that becomes unwieldy.
What we need is an abstraction over asynchronous operations, and that
is the main idea of a CSP-derived system called “Concurrent ML”
(CML). Originally implemented as a library on top of Standard ML of
New Jersey by John Reppy, CML provides this abstraction, which in
Fibers is called an operation1. Calling
send-operation on a channel returns an operation, which is just
a value. Operations are like closures in a way; a closure wraps up
code in its environment, which can be later called many times or not
at all. Operations likewise can be performed2 many times or not at all; performing an operation
is like calling a function. The interesting part is that you can
compose operations via the
choice-operation combinators. The former lets you bundle up an
operation and a continuation. The latter lets you construct an
operation that chooses over a number of operations. Calling
perform-operation on a choice operation will perform one and
only one of the choices. Performing an operation will call its
wrap-operation continuation on the resulting values.
While it’s possible to implement Concurrent ML in terms of Go’s
channels and baked-in
select statement, it’s more expressive to
do it the other way around, as that also lets us implement other
operations types besides channel send and receive, for example
timeouts and condition variables.
1.2 Fibers design
In Fibers, the unit of computation is the fiber, a lightweight
thread managed by Guile. A fiber communicates with the world via
normal Guile ports:
put-string, and all
that. Between themselves, fibers send and receive Scheme values over
Whenever a fiber tries to read but no data is available, or tries to write but no data can be written, Guile will suspend the fiber and arrange for it to be resumed when the port or channel operation can proceed. In the meantime, Guile will run other fibers. When no fiber is runnable, Guile will use efficient system facilities to sleep until input or output can proceed.
When a fiber would block, it suspends to the scheduler from the
current thread. The scheduler will arrange to re-start the fiber when
the port or channel becomes readable or writable, as appropriate. For
ports, the scheduler adds the file descriptor associated with the port
epoll set. In either case, the scheduler remembers which
fibers are waiting and for what, so that the user can inspect the
state of their system.
Currently in Fibers there is no ambient scheduler running; an error is
signalled if a user calls
spawn-fiber while not inside a
On the Scheme level, a fiber is a delimited continuation. When a scheduler runs a fiber, it does so within a prompt; when the fiber suspends, it suspends to the prompt. The scheduler saves the resulting continuation as part of the fiber’s state. In this way the per-fiber computational state overhead is just the size of the pending stack frames of the fiber, which can be just a handful of words.
Currently fibers are pinned to the kernel thread in which they are created. We should probably implement some kind of work-stealing behavior so that if you choose to devote multiple CPU cores to servicing fibers, that they can share the workload.
Ports are how fibers communicate with the world; channels are how fibers communicate with each other. Channels are meeting places between fibers. A fiber that goes to send a message over a channel will block until there is a fiber ready to receive the message, and vice versa. Once both parties are ready, the message is exchanged and both parties resume. There can be multiple fibers waiting to read and write on a channel, allowing channels to express not only pipelines but also common concurrency patterns such as fan-in and fan-out.
Unlike Erlang channels, channels in Fibers are purely local and do not attempt to provide the illusion of network transparency. This does have the positive advantage that we are able to provide better backpressure support than Erlang, blocking when no receiver is available to handle a message instead of letting the sender keep sending many messages.
On the other hand, currently fibers default to not being preemptively scheduled. A fiber will only suspend when it would block on channel receive or send, or on read or write on a port. This would be an OK point in the design space if only one kernel thread could be running fibers at once, as in Node.js. However given that this is not the case, Fibers does not have many of the concurrency invariants that such systems enjoy, so perhaps we should default to enabling preemption.
To avoid starvation, a fiber can only run once within a “turn”. Each turn starts with a poll on file descriptors of interest and marks the associated fibers as runnable. If no fiber is runnable at the start of the poll, the poll call will ask the kernel to wait for a runnable descriptor. Otherwise the poll call will ask the kernel to return immediately. There is an additional FD added to the poll set that is used to interrupt a blocking poll, for example if a fiber becomes runnable due to I/O on a channel from a separate kernel thread while the first scheduler was still polling.
To enable expressive cross-kernel-thread communications, channel sends and receives are atomic and thread-safe.
To start scheduling fibers, user code will typically create a scheduler, instate it on the thread, add some fibers, then run the scheduler. That call to run the scheduler will only return when there there are no more fibers waiting to be scheduled.
2 API reference
Fibers is a library built on Guile, consisting of a public interface, base support for asynchronous operations, implementations of operations for channels and timers, and an internals interface.
|• Using Fibers:||User-facing interface to fibers|
|• Operations:||Composable abstractions for concurrency.|
|• Channels:||Share memory by communicating.|
|• Timers:||Operations on time.|
|• REPL Commands:||Experimenting with Fibers at the console.|
|• Internals:||Scheduler and fiber objects and operations.|
2.1 Using Fibers
The public interface of fibers right now is quite minimal. To use it,
To create a new fibers scheduler and run it in the current Guile
Function: run-fibers [init-thunk=
(make-scheduler)] [#:keep-scheduler?] [#:hz=0]
Run init-thunk within a fiber in a fresh scheduler, blocking until the scheduler has no more runnable fibers. Return the value(s) returned by the call to init-thunk.
(run-fibers (lambda () 1)) ⇒ 1 (run-fibers (lambda () (spawn-fiber (lambda () (display "hey!\n"))))) -| hey!
run-fiberswill ensure that Guile’s port implementation allows fibers to suspend if a read or a write on a port would block. See Non-Blocking I/O in Guile Reference Manual, for more details on suspendable ports. If for some reason you want port reads or writes to prevent other fibers from running, pass
run-fiberswill create a fresh scheduler. If you happen to have a pre-existing scheduler (because you used the internals interface to create one), you can pass it to
By default hz is 0, indicating that running fibers should never be preempted, and should instead run until they need to wait on some operation. That is to say, the default scheduling mode is cooperative. Pass a higher value to cause computationally expensive tasks to be preempted if possible. Note that preemption will only occur if the fiber can actually be suspended; See Barriers, for more information.
The scheduler will be destroyed when
run-fibersfinishes, unless the scheduler was already “current” (see Internals). If you need to keep the scheduler, either make sure it is current or explicitly pass
Function: spawn-fiber thunk [scheduler=
Spawn a new fiber that will run thunk. Return the new fiber. The new fiber will run concurrently with other fibers.
The fiber will be added to the current scheduler, which is usually what you want. It’s also possible to spawn the fiber on a specific scheduler, which is useful to ensure that the fiber runs on a different kernel thread. In that case, pass the
Currently, fibers will only ever be run within the scheduler to which they are first added, which effectively pins them to a single kernel thread. This limitation may be relaxed in the future.
The fiber will inherit the fluid–value associations (the dynamic state) in place when
spawn-fiberis called. Any
fluid-set!or parameter set within the fiber will not affect fluid or parameter bindings outside the fiber.
- Function: current-fiber
Return the current fiber, or
#fif not called within the dynamic extent of a thunk passed to
- Function: sleep seconds
Wake up the current fiber after seconds of wall-clock time have elapsed. This definition will replace the binding for
sleepin the importing module, effectively overriding Guile’s “core” definition.
Operations are first-class abstractions for asynchronous events.
There are primitive operation types, such as waiting for a timer
(see Timers) or waiting for a message on a channel
(see Channels). Operations can also be combined and transformed
wrap-operation from this module:
(use-modules (fibers operations))
- Function: wrap-operation op f
Given the operation op, return a new operation that, if and when it succeeds, will apply f to the values yielded by performing op, and yield the result as the values of the wrapped operation.
- Function: choice-operation . ops
Given the operations ops, return a new operation that if it succeeds, will succeed with one and only one of the sub-operations ops.
Finally, once you have an operation, you can perform it using
- Function: perform-operation op
Perform the operation op and return the resulting values. If the operation cannot complete directly, block until it can complete.
See Introduction, for more on the “Concurrent ML” system that introduced the concept of the operation abstraction.
There is also a low-level constructor for other modules that implement primitive operation types:
This is a low-level constructor, though; if you ever feel the need to
make-base-operation, make sure you’re familiar with the
Concurrent ML literature. Godspeed!
Channels are the way to communicate between fibers. To use them, load the channels module:
(use-modules (fibers channels))
- Function: put-operation channel message
Make an operation that if and when it completes will rendezvous with a receiver fiber to send message over channel.
- Function: get-operation channel
Make an operation that if and when it completes will rendezvous with a sender fiber to receive one value from channel.
- Function: put-message channel message
Send message on channel, and return zero values. If there is already another fiber waiting to receive a message on this channel, give it our message and continue. Otherwise, block until a receiver becomes available.
(perform-operation (put-operation channel message))
- Function: get-message channel
Receive a message from channel and return it. If there is already another fiber waiting to send a message on this channel, take its message directly. Otherwise, block until a sender becomes available.
(perform-operation (get-operation channel))
Channels are thread-safe; you can use them to send and receive values between fibers on different kernel threads.
Timers are a kind of operation that, you guessed it, let you wait until a certain time.
(use-modules (fibers timers))
- Function: wait-operation seconds
Make an operation that will succeed with no values when seconds have elapsed.
- Function: timer-operation expiry
Make an operation that will succeed when the current time is greater than or equal to expiry, expressed in internal time units. The operation will succeed with no values.
2.5 REPL Commands
Fibers implements some basic extensions to the Guile command-line
interface (its Read-Eval-Print Loop, or the REPL). Prefix these
commands with a comma (
,) to run them at the REPL; see
,help fibers for full details, once you have loaded the
(fibers) module of course.
- REPL Command: kill-sched sched
Shut down the scheduler named sched. Use
,schedsto list scheduler names.
- REPL Command: fibers [sched]
Show a list of all fibers. If sched is given, limit to fibers bound to the given scheduler.
- REPL Command: spawn-fiber exp [sched]
Spawn a new fiber that runs exp. If sched is given, the fiber will be spawned on the given scheduler.
These internal interfaces are a bit dangerous, in the sense that if they are used wrongly, they can corrupt the state of your program. For example, the scheduler has some specific mechanisms to ensure thread-safety, and not all of the procedures in this module can be invoked on a scheduler from any thread. We will document them at some point, but for now this section is a stub.
(use-modules (fibers internal))
- Function: make-scheduler
Make a new scheduler in which to run fibers. hz indicates the frequency at which fibers should be preempted.
- Special Form: with-scheduler scheduler body ...
(begin body ...)in an environment in which scheduler is bound to the current kernel thread and marked as current. Signal an error if scheduler is already running in some other kernel thread.
- Function: run-scheduler sched
Run sched until there are no more fibers ready to run, no file descriptors being waited on, and no more timers pending to run. Return zero values.
- Function: resume-on-readable-fd fd fiber
Arrange to resume fiber when the file descriptor fd becomes readable.
- Function: resume-on-writable-fd fd fiber
Arrange to resume fiber when the file descriptor fd becomes writable.
- Function: resume-on-timer fiber expiry get-thunk
Arrange to resume fiber when the absolute real time is greater than or equal to expiry, expressed in internal time units. The fiber will be resumed with the result of calling get-thunk. If get-thunk returns
#f, that indicates that some other operation performed this operation first, and so no resume is performed.
- Function: create-fiber sched thunk
Spawn a new fiber in sched with the continuation thunk. The fiber will be scheduled on the next turn.
- Function: kill-fiber fiber
Try to kill fiber, causing it to raise an exception. Note that this is currently unimplemented!
- Function: fold-all-schedulers f seed
Fold f over the set of known schedulers. f will be invoked as
(f name scheduler seed).
- Function: scheduler-by-name name
Return the scheduler named name, or
#fif no scheduler of that name is known.
- Function: fold-all-fibers f seed
Fold f over the set of known fibers. f will be invoked as
(f name fiber seed).
- Function: suspend-current-fiber [after-suspend]
Suspend the current fiber. Call the optional after-suspend callback, if present, with the suspended thread as its argument.
- Function: resume-fiber fiber thunk
Resume fiber, adding it to the run queue of its scheduler. The fiber will start by applying thunk. A fiber must only be resumed when it is suspended. This function is thread-safe even if fiber is running on a remote scheduler.
- Function: scheduler-kernel-thread sched
Return the kernel thread on which sched is running, or
#fif sched is not running.
Running Guile code within a fiber mostly “just works”. There are a few pitfalls to be aware of though.
|• Blocking:||Avoid calling blocking operations.|
|• Barriers:||Avoid suspending inside continuation barriers.|
|• Mutation:||Avoid unstructured mutation of shared data.|
|• Mutexes:||Mutexes and fibers don’t mix very well.|
When you run a program under fibers, the fibers library arranges to make it so that port operations can suspend the fiber instead of block. This generally works, with some caveats.
- The port type has to either never block, or support non-blocking I/O. Currently the only kind of port in Guile are file ports (including sockets), and for them this condition is fulfilled. However notably non-blocking I/O is not supported for custom binary I/O ports, not yet anyway. If you need this, get it fixed in Guile :)
- You have to make sure that any file port you operate on is opened in
nonblocking mode. See Non-Blocking I/O in Guile Reference
Manual, for the obscure
fcntlincantation to use on your ports.
- You have to avoid any operation on ports that is not supported yet in
Guile for non-blocking I/O. Since non-blocking I/O is new in Guile,
only some I/O operations are expressed in terms of the primitive
operations. Notably, Scheme
writeare still implemented in C, which prevents any fiber that uses them from suspending and resuming correctly. What will happen instead is that the call blocks instead of suspending. If you find a situation like this, talk to Guile developers to get it fixed :)
- You can enable non-blocking I/O for local files, but Linux at least will always say that the local file is ready for I/O even if it has to page in data from a spinning-metal device. This is a well-known limitation for which the solution is apparently to do local I/O via a thread pool. We could implement this in Fibers, or in Guile... not sure what the right thing is!
You also have to avoid any other library or system calls that would
block. One common source of blocking is
related network address resolution library calls. Again, apparently
the solution is thread pools? Probably in Fibers we should implement
a thread-pooled address resolver.
(fibers) module exports a
sleep replacement. Code
that sleeps should import the
(fibers) module to be sure that
they aren’t using Guile’s
Finally, a fiber itself has to avoid blocking other fibers; it must
reach a “yield point” some time. A yield point includes a read or
write on a port or a channel that would block, or a
Other than that, nothing will pre-empt a fiber, at least not
currently. If you need to yield to the scheduler, then at least do a
(sleep 0) or something.
When a fiber suspends, Fibers uses
abort-to-prompt to save the
fiber’s continuation, saving each pending computation in that fiber to
the heap. When the fiber resumes, Fibers invokes the saved
continuation, effectively replaying these saved stack frames back onto
the current stack. For this operation to succeed, the saved
continuation needs to be suspendable. A suspendable
continuation should be able to be resumed after the call to
Most continuations in Guile are suspendable. However, not all of them are. It’s possible to explicitly instate a continuation barrier (see Continuation Barriers in Guile Reference Manual) that will allow the continuation to be aborted but not reinstated:
;; If put-message suspends, we will never resume! (run-fibers (lambda () (with-continuation-barrier (lambda () (put-message channel 42)))))
put-message call can’t succeed directly, then the fiber
will suspend. However when the fiber becomes runnable again, it can’t
be rewound because of the barrier. Because this is the case, when
Fibers goes to suspend a computation but realizes that the suspended
fiber could never be resumed, it throws an error instead.
with-continuation-barrier is the only function in Guile that
establishes a continuation barrier on purpose. However there are
number of other functions that accidentally establish a continuation
barrier by recursing into C code and then back to Scheme. (Guile can
only rewind the state of a saved computation if Guile created the
corresponding stack frame, and that’s not the case for the
intermediate stack frame created by the C compiler.)
Accidental continuation barriers are bugs, and the Guile developers have been working on removing them over the years. By now, most of the high-priority accidental barriers are gone. Those that are left include:
- The body thunk of
- GOOPS methods attached to a primitive-generic like
- Dynwind entry/exit handlers, but only when called due to nonlocal entry or exit
- R6RS custom binary port callbacks
- Legacy “soft port” callbacks
- R5RS “delay” callbacks
- Many module system callbacks (module transformers, etc)
- SRFI-13 string and character-set callbacks
- Callbacks from some SRFI-1 functions
- Callbacks from
- Custom hash table assoc functions
- Calls to
load-from-path(though, oddly, not
- Object printers, e.g. custom record printers
array-mapand related array functions
This set will be reduced over time as more of
rewritten in Scheme.
Finally, for port operations, See Non-Blocking
I/O in Guile Reference Manual. When Guile tries to read
from a file descriptor and nothing is available, normally it would
call the current read waiter, which Fibers customizes to suspend the
fiber and run another one in the meantime. However for procedures
that have not been rewritten in terms of the “suspendable port
operations”, notably including
display, the nothing-to-read condition is handled in C, not
Scheme, so Guile cannot create a resumable continuation. In this
case, instead of erroring, Guile will wait until the file descriptor
is readable or writable (as appropriate) and then continue. However
in the meantime, which may be forever, this blocks other fibers from
running. Therefore Fibers users sometimes have to be aware of the
state of Guile’s rewrite of port operations in terms of
suspendable-port primitives, and to help out if things aren’t moving
fast enough :)
Although code run within fibers looks like normal straight-up Scheme,
it runs concurrently with other fibers. This means that if you mutate
shared state and other fibers mutate the same shared state using
normal Scheme procedures like
vector-set!, or the
like, then probably you’re going to have a bad time. Even with the
default cooperative scheduling mode, multi-step transactions may be
suspended if your code reaches a yield point in the middle of
performing the transaction.
Of course if you enable preemption or have multiple kernel threads running fiber schedulers and you still use unstructured mutation, then it could indeed be that you have many more possible system states.
The best way around this problem is to avoid unstructured mutation, and to instead share data by communicating over channels. Using channels to communicate data produces much more robust, safe systems.
If you need to mutate global data, the best way is to use an atomic variable. If that is not possible, then consider spawning a fiber to manage the mutable data, and communicating with that fiber over channels. Mutexes are also an option but are difficult to use correctly; see the considerations from the following section.
Mutexes are low-level synchronization primitives provided by Guile. Used properly, they can be used to build concurrent systems that concurrently access data without corrupting it.
See Mutexes and Condition Variables in Guile Reference Manual, for some reasons why mutexes aren’t so great for Guile in general.
Guile’s mutexes are an even worse solution with a Fibers system. It is a bad idea for a fiber to grab a Guile mutex, because if the mutex is not available, Guile will suspend not just the fiber that is running but the entire kernel thread. If the mutex is available, the fiber obtains it, cool; but if it the fiber suspends while holding a mutex, that’s bad news. Any fiber trying to acquire a mutex while a suspended fiber from the same thread already has the mutex will result in an error: as Guile thinks that the mutex has already been acquired by the current thread, it detects recursion and bails out.
With condition variables, similar problems arise: waiting on a condition variable will block indefinitely, if the condition can only be signalled by another fiber in the current kernel thread.
The root of this problem is that Guile associates mutexes with kernel threads, not fibers. It would be possible however to make a Fibers-appropriate implementation of mutexes, but we suggest that users try atomic boxes or channels instead. If you do use mutexes, take care to never suspend a fiber while it owns any mutex.
Here are some small examples to get you started.
|• Ping:||An echo server and client.|
|• Memcached:||A simple memcached server and client.|
|• Web Server:||Guile’s non-blocking web server.|
More examples would be great, especially demonstrating interesting things that can be done with channels.
This simple server listens on a TCP port, echoing lines back to any
user that connects. This file can be found in
examples/ping-server.scm, and can be run from the build dir as
./env guile examples/ping-server.scm.
First, we use some standard Guile modules, and the fibers module.
(use-modules (rnrs bytevectors) (fibers) (ice-9 textual-ports) (ice-9 rdelim) (ice-9 match))
We run the server within a
(define* (run-ping-server #:key (host #f) (family AF_INET) (addr (if host (inet-pton family host) INADDR_LOOPBACK)) (port 11211) (socket (make-default-socket family addr port))) (listen socket 1024) (sigaction SIGPIPE SIG_IGN) (socket-loop socket (make-hash-table))) (run-fibers run-ping-server)
Up to here, all good. Perhaps we should look at how to open a socket; here are a couple helpers that appear often in applications that use suspendable ports. See Non-Blocking I/O in Guile Reference Manual, for full details.
(define (set-nonblocking! port) (fcntl port F_SETFL (logior O_NONBLOCK (fcntl port F_GETFL))) (setvbuf port 'block 1024)) (define (make-default-socket family addr port) (let ((sock (socket PF_INET SOCK_STREAM 0))) (setsockopt sock SOL_SOCKET SO_REUSEADDR 1) (fcntl sock F_SETFD FD_CLOEXEC) (bind sock family addr port) (set-nonblocking! sock) sock))
We hope to make this easier in the future; it’s a bit too much ceremony. Now, the main dish is the server loop, that simply accepts new connections, forking off a fiber for each connection:
(define (socket-loop socket store) (let loop () (match (accept socket) ((client . addr) (set-nonblocking! client) ;; Disable Nagle's algorithm. We buffer ourselves. (setsockopt client IPPROTO_TCP TCP_NODELAY 0) (spawn-fiber (lambda () (client-loop client addr store))) (loop)))))
Finally, the loop to handle a single client:
(define (client-loop port addr store) (let loop () ;; TODO: Restrict read-line to 512 chars. (let ((line (read-line port))) (cond ((eof-object? line) (close-port port)) (else (put-string port line) (put-char port #\newline) (force-output port) (loop))))))
This ping server is fairly straightforward, and is only flawed in a couple of ways: it doesn’t limit the line size, and so is vulnerable to memory exhaustion if the client gives it a very, very big line, and additionally, it does not time out clients after inactivity, so the poll set could get quite large.
In practice the limit for the number of connections is imposed by the
system in the form of a file descriptor limit. Use
to increase this limit on the console, or
setrlimit to increase
it from Guile, within the hard limits imposed by the system.
The client is similar to the server; see
examples/ping-client.scm for full details. It can be run as
./env guile examples/ping-client.scm N M, to make N concurrent
connections to the server and make a series of M requests on each
connection. It spawns a fiber per connection, and then uses a normal
Guile loop to make the serial requests.
(define (run-ping-test num-clients num-connections) ;; The getaddrinfo call blocks, unfortunately. Call it once before ;; spawning clients. (let ((addrinfo (car (getaddrinfo "localhost" "11211")))) (let lp ((n 0)) (when (< n num-clients) (spawn-fiber (lambda () (client-loop addrinfo n num-connections))) (lp (1+ n))))))
Running this on a laptop from 2015 yields results more or less like this:
$ time ./env guile examples/ping-client.scm 1000 100 real 0m2.478s user 0m1.632s sys 0m0.552s
That’s a throughput of somewhere around 40000 fiber switches per second on each side, which is none too shabby.
Similarly to the echo server, Fibers includes an example memcached server and client. Run the server like this:
$ ./env guile examples/memcached-server.scm
Run the client as with the ping client:
$ time ./env guile examples/memcached-client.scm 1000 100 real 0m8.399s user 0m6.492s sys 0m1.456s
Here we see a throughput of around 12000 puts plus 12000 gets per second; pretty good for a basic implementation.
4.3 Web Server
Fibers includes a “backend” for Guile’s built-in web server that
uses fibers. To run a web server that serves each client from fibers,
fibers backend when running your web server:
(use-modules (web server)) (define (handler request body) (values '((content-type . (text/plain))) "Hello, World!")) (run-server handler 'fibers)
Performance seems to be on par with the standard web server backend implementation shipped with Guile, though it is not as battle-hardened. See Barriers, as well, for things that need improving on the Guile side of things.
5 Project status
It’s early days. At the time of this writing, no one uses fibers in production that we are aware of. Should you be the first? Well maybe, if you feel like you understand the implementation, are prepared to debug, and have some time on your hands. Otherwise probably it’s better to wait.
TODO.md file in the repository for a current list of
CML uses the term event, but we find this to be a confusing name.
In CML, synchronized.