First we have our source, which just write all the integers starting from 0 down the channel out. The type %>int is an output channel endpoint for int.

examples/corout/ex1.flx

  proc source (out: %>int) () {
    var i = 0;
    while true do 
      write (out,i); 
      ++i; 
    done
  }

Now we have a simple sink, which just prints everything it reads:

examples/corout/ex1.flx

  proc sink (inp: %<int) () {
    while true do 
      var i = read inp;
      println$ i;
    done
  }

You should note the extra unit parameter (). After the input is bound, the resulting procedure will have type

  unit -> unit

which is the type required to spawn fibre from a coroutine.

Now we have a transducer which writes the square of every integer it reads.

examples/corout/ex1.flx

  proc squarer (inp: %<int, out: %>int) () {
    while true do 
      var i = read inp;
      write (out, i * i);
    done
  }

You should notice the previous three components were all infinite loops. Since we don't want our demo to run forever we will throw in a limiter chip:

examples/corout/ex1.flx

  proc limiter (var limit: int) (inp: %<int, out: %>int) () {
    while limit > 0 do
      var i = read inp;
      write (out, i);
      --limit;
    done
  }

This procedure drops through, but it cannot return control, because there is nowhere to return it to, so it has, in effect, committed suicide implicitly.

Now we need have four components so we need three channels to connect them:

examples/corout/ex1.flx

  proc run_pipeline() {
    // make channels
    var i1,o1 = mk_ioschannel_pair[int](); 
    var i2,o2 = mk_ioschannel_pair[int](); 
    var i3,o3 = mk_ioschannel_pair[int](); 
  
    // make coroutines by binding the channels
    var d1 = source(o1);
    var d2 = squarer(i1,o2);
    var d3 = limiter 8 (i2,o3);
    var d4 = sink (i3);
  
    // spawn coroutines as fibres
    spawn_fthread d1;
    spawn_fthread d2;
    spawn_fthread d3;
    spawn_fthread d4;
   
    // exit
  }
  run_pipeline();

Here is the complete program: ex1.flx

It is clear, because I told you, that we put the limiter into the pipeline so it terminates. So the limiter commits suicide by dropping off the end after a certain number of data transfers. But the other three components are infinite loops, so how does the system terminate?

First consider the transducer squarer tries to write to the limiter, but alas, it is dead? The write stalls, and we say the fibre is blocked or being vulgar, constipated. And now, since it is blocked, it cannot read the input from the source, so it too is blocked.

The sink on the other hand has a different problem: it is trying to read from the limiter but the limiter is dead, so there is no input coming: the sink is said to be starved.

There are therefore no active fibres so the system terminates. I will emphasise this point heavily because these are the correct termination semantics. There is another language with processes and channels, namely golang. Unfortunately golang got the termination semantics completely wrong. in addition, golang channel semantics are also wrong because channels can be closed and a reader can detect if a writer closed the channel.

Although this is not possible in Felix, you can write the option type opt and use the None case to signal end of data. In fact, in Felix you can write any type down a channel, even channels!

Most programming language generate programs which consist of single top level procedure, for example main() in C. It is a subroutine called by the startup code which in turn was invoked by the operating system.

Felix, as usual, is different. For a start, Felix generates libraries, in fact the default is a shared library. So in fact, what you think is mainline code running is in fact just the initialisation code for the library. You can also add a procedure flx_main() to your code and that will also be run after the initialisation of the library.

However there is something else different: the Felix mainline code is not a subroutine, it is a coroutine! The mainline can happily terminate and leave other fibres running: there's really nothing special about your main program code, it's just another coroutine.

The Felix startup code creates a scheduler to run coroutines, and your program code is just the initial coroutine. So your program terminates when there is nothing left to do precisely because it's just another coroutine.

There is a constraint on Felix coroutines: they have to be procedures. Functions cannot read and write channels. However there is a way around this problem: you can use the run subroutine to create an run a new, nested, scheduler.

The run subroutine, being a subroutine, returns when it is finished.

Unfortunately there is another constraint on nested schedulers: they cannot do asynchronous I/O.

4.1.1 write

4.1.2 read

4.1.3 suicide

4.1.4 spawn

4.1.5 Scheduler operation

The description above is a complete account of the abstract semantics known as Communicating Sequential Coroutines or CSC, it is a sub system obtain from Tony Hoare's Communicating Sequenmtial Processes or CSP, in which concurrency is replaced by an indeterminate total ordering.

To be precise in CSC all events are totally ordered, however the exact ordering is not determinate. This is because a scheduler running the system is free to pick any active fibre to run when one is needed; similarly a read or write operation can match with any dual operation on a channel.

In the Felix implementation, a spawned fibre runs immediately if the spawn_fthread procedure is used to launch it, or the running fibre continues instead, of schedule_fthread is used instead.

In addition, I/O transfers always result in the reader proceeding, to give it a chance to actually fetch the data before the write might modify it.