# 2021q1 Homework5 (quiz5)
contributed by < `RZHuangjeff` >
###### tags: `linux2021`
> [Problem set](https://hackmd.io/@sysprog/linux2021-quiz5)

## Problem 2
### Description
This is a program that helps to handle coroutines of a process. With coroutine, a program can switch to other routine while the current executing routine is waiting for certain conditions happend, rather than blocks entire program. To be able to resume the execution point of former routine, a GCC extension called [Labels as Values](https://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html) performs the key role, since it allows the address of a label being saved and jump (`goto`) to it later, via saved address.
The typical use case of coroutine is to maintain I/O operations between different input sources and ouput destinations. Just like the example shown in the quiz, which handles I/O operations between standard I/O and a socket, those operations are executed simultaneously, which means that block waiting on standard input will not cause reading from socket being blocked.
For the example shown in quiz, a wait on a condition is performed by macro `cr_wait`, once the condition that it waits for has not happened yet, this macro will return from the current function after address of the checkpoint, a unique label generated automaticaly, is saved. While that function is invoked later, macro `cr_begin` will realize that a checkpoint was saved and will jump to that checkpoint to resume execution. By wrapping several routines that should be executed simultaneously in a loop, next routine will be invoked while previous one is waiting.

### Improvements
> commit [c8d6f79](https://github.com/RZHuangJeff/quiz5/commit/c8d6f790697aa88f4781748cb3240e78d37723b0)

The original version of coroutine implemented in quiz 5 has basic functions that performs coroutine, but there are several cons I discovered:

* **misuse macros**
With the origin definition of macros, one may writes program as following:

    void main_loop()
    {
        struct cr routine1 = cr_init();
        struct cr routine2 = cr_init();
        
        while (cr_state(&routine1) != CR_FINISHED &&
               cr_state(&routine2) != CR_FINISHED) {
            cr_begin(&routine1);
            ...
            cr_wait(&routine1, /* cond to wait */);
            ...
            cr_end(&routine1);
            
            cr_begin(&routine2);
            /*body of routine2 */
            cr_end(&routine2);
        }
    }

which may lead to unexpected result since once the condition being waited in line 10 has not happened yet, the program will return from `main_loop`, rather than execute next routine, although such program makes sence.
To avoid such misusing, using of such macros should be limited in particular functions. To fulfill that, the argument `o` of all macros that should be limited are removed, instead, the context of coroutine mentioned in those macros is hardcoded as `__ct`. A macro `cr_func_def` is introduced that is used when someone wants to define a coroutine function, those functions contain a single argument named `__ct` that represents context corresponding to that routine. Following is definition of `cr_func_def` macro:

    #define cr_func_name(name) cr_func_##name

    #define cr_func_def(name) \
        static void cr_func_name(name)(struct cr *__ct)

And one may define a routine like:

    cr_func_def(sample_routine)
    {
        /* initializations */
        
        cr_begin();
        
        /* body of routine */
        
        cr_end();
        
        /* finalizations */
    }

With these changes, compiler will report errors for the program shown above.

* **`cr_context` and `cr_run`**
The macro `cr_context` helps to declare a `struct cr` variable, which acts as context of specific coroutine.
The macro `cr_run` is a wrapper that wraps invocation of coroutine function with its context. If there is no declaration of such coroutine or context for such coroutine, a compilation error will be reported, this helps one to make sure that all required job was done.
Following are definitions of macros mentioned above:

    #define cr_context_name(name) cr_context_##name
    #define cr_context(name) struct cr cr_context_name(name)
    
    #define cr_run(name) cr_func_name(name)(&cr_context_name(name))

* **field local**
In the definition of `struct cr`, we can find that there is a pointer named `local`, which is declared but not used.
Since we have introduced a series of macro that help defining routine functions, with this definition of routine function, there is no way to pass arguments to these functions. To deal with such problem, the macro `cr_init` is modified and renamed as `cr_context_init` which accepts a pointer that will be assigned to `local`.
To reference variable that is pointed by `local`, one may use one of following two macros: `cr_priv_var` or `cr_grab_priv_var`, the first macro will cast `__ct->local` to a pointer of given type, while second one will return a pointer that points to the given field with in the structure that `__cr->local` points to. Following are definitions of those macros:

    #define cr_grab_priv_var(type, memb) &((type*) (__ct->local))->memb

    #define cr_priv_var(type) ((type *) (__ct->local))

* **`cr_local` macro**
A macro `cr_local` is introduced to wrap declaration of static local variables, which aims to highlight that such variable is a part of coroutine. Following is definition of `cr_local`:

    #define cr_local static