otp_src_25.0.2.tar.gz

Yielding C Fun ============== Introduction ------------ Yielding C Fun (YCF) is a tool that transforms functions written in a subset of the C programming language so that they become yieldable. A yieldable function can be suspended/yielded/paused/trapped (either automatically or where the user has inserted a particular statement) and then be resumed at a later point. Yileldable functions are also called [coroutines](https://en.wikipedia.org/wiki/Coroutine). Difference Between Yielding C Fun and Coroutine Libraries --------------------------------------------------------- Several libraries implement [coroutine support for the C programming language](https://en.wikipedia.org/wiki/Coroutine#Implementations_for_C) (e.g., \[[1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]\]). These libraries either rely on platform-specific code or do not save call stack variables. Yielding C Fun (YCF) does not have any of these two limitations. YCF can accomplish this as it is a source-to-source transformation tool and not only a library. YCF has been created to make it easier to implement yielding Erlang [NIFs](http://erlang.org/doc/tutorial/nif.html) and [BIFs](http://erlang.org/pipermail/erlang-questions/2009-October/046899.html) (i.e., Erlang functions that are written in C). Below are examples of YCF features that are useful when implementing yielding Erlang NIFs and BIFs: * YCF automatically generates a destroy function for each yieldable function. The destroy function frees resources that are used by a suspended function. The destroy function is useful when a suspended function needs to abort (e.g., when the Erlang process that invoked the function has died). * YCF can automatically insert code that yields functions after a user specifiable number of loop iterations and goto statements. * YCF has a hook system that lets the user insert code that is triggered when certain events happen (e.g., when a function yields). The main limitations of YCF are that it cannot handle all valid C code and that it cannot make library functions without source code yieldable. Pointers to stack-allocated data are also not allowed (YCF has a memory allocation function called `YCF_STACK_ALLOC` to work around this issue). Requirements ------------ * A C99 compatible C compiler * make (optional but useful for building) Compile and Test ---------------- Build the executable `$YCF_ROOT/bin/yielding_c_fun.bin`: make Build the executable and run all tests: make test Getting Started --------------- A brief introduction tutorial can be found [here](doc/thread_tutorial.md). This tutorial is a perfect place to start! The "[test/examples/](test/examples/)" folder in this repository contains many small examples that are useful when learning about YCF. YCF's automatic tests use these examples as well. The driver for these tests is located in `test/test.sh`. [This Erlang NIF example](test/examples/sha256_erlang_nif/) shows how one can use YCF to write a yielding Erlang NIF library. Command Line Parameters ----------------------- ``` Usage: yielding_c_fun [-h] yielding_c_fun [-use_gc [-print_gc_info]] [-log_max_mem_usage log_file] [(( -f | -frec | -fnoauto ) function_name)... [-output_file_name output_file] [-header_file_name header_file] [-debug] [-only_yielding_funs] [-static_aux_funs] input_c_file]] ``` * `-h` Print help text * `-use_gc` Use garbage collection. The garbage collection system assumes that the C call stack consists of a continuous memory block and is therefore not enabled by default even though this assumption is valid on all major platforms. YCF does not reclaim any allocated memory if the `-use_gc` flag is not set. * `-print_gc_info` (For debugging) Print garbage collection information to `stderr` * `-log_max_mem_usage log_file` (For debugging) Print the peak memory usage of the tool to the file `log_file` * `-fnoauto function_name` Generate a yieldable version of the function named function_name. The user can use `YCF_YIELD()`, `YCF_YIELD_NO_REDS()`, and `YCF_CONSUME_REDS(N)` to control when and where the function should yield. See the section titled "Special Statements and Macros" for more information. * `-f function_name` Generate a yieldable version of the function named `function_name`. The generated function automatically decrements the reduction counter by one at the beginning of loop bodies and before goto statements. The function yields automatically if the reduction counter reaches a value that is zero or smaller after it has been decremented. * `-frec function_name` Same as the `-f` option with the exception that the generated function also decrements one reduction before calls to other yieldable functions and before returning. The function yields automatically if the reduction counter reaches a value that is zero or smaller after it has been decremented. * `-fexternal function_name` YCF expects that a yielding version of the function called `function_name` is generated externally. Calls to the function called `function_name` from yielding functions calls the externally generated yielding version of the function called `function_name`. * `-output_file_name output_file` Output the generated code to a file named output_file. The output is printed to standard output if this parameter is unspecified. * `-header_file_name header_file` Generate a header file containing only declarations for the generated functions and write the header file to the file named header_file. * `-debug` Generate debug code that executes when a function yields. The debug code searches the call stack of the yielding functions for pointers to data that is allocated on the call stack. The program crashes with an error message if any such pointer is found. The generated debug code depends on that a function called `ycf_debug_get_stack_start()` is declared somewhere in the program. The `ycf_debug_get_stack_start()` functions should return a value of type `void*`. Example: static _Thread_local void* ycf_debug_global_stack_start_ptr = NULL; void* ycf_debug_get_stack_start() { return ycf_debug_global_stack_start_ptr; } If `ycf_debug_get_stack_start()` returns `NULL`, the value of the `ycf_yield_state` parameter will be used as the start of the stack (it is assumed that the stack grows towards lower addresses). If `ycf_debug_get_stack_start()` returns something different than `NULL`, that value will be used as the start of the stack. To check that nested yielding functions do not have pointers to the call stack, one have to make sure that `ycf_debug_get_stack_start()` returns something different than `NULL` (otherwise, each function will just check for pointers to its own frame). Example: ycf_debug_global_stack_start_ptr = &wb; ret = fun_ycf_gen_yielding(&nr_of_reductions,&wb,NULL,allocator,freer,NULL,0,NULL,1); ycf_debug_global_stack_start_ptr = NULL; * `-only_yielding_funs` Print only the generated functions and struct declarations. The default behavior is to insert the generated functions into a copy of the input source file. * `-static_aux_funs` Make the generated auxiliary functions static (i.e., local to the C compilation unit) * `input_c_file` The source file containing the functions that YCF shall create yieldable versions of. YCF does not do any macro expansions. There are several restrictions on the code that YCF can handle that are described in the "Code Restrictions" section below. Generated Functions ------------------- YCF generates three functions for each function name that it is given. These functions have