<commit_before>Fluxcapacitor
----

Fluxcapacitor is a tool for Linux, originally created to speed up
[SockJS](http://sockjs.org) tests.

It is somewhat similar to tools like:

 * [FreezeGun](http://stevepulec.com/freezegun/) for Python
 * [timecop](https://github.com/travisjeffery/timecop) or
   [Delorean](https://github.com/bebanjo/delorean) for Ruby
 
Instead of patching time libraries in high level programming language,
Fluxcapacitor "patches" low-level syscalls using `ptrace` on Linux.

This approach has a significant advantage: now you can run more than
one independent processes that will be affected by speeding up the
time. This is especially useful for testing network protocols.

Basic examples
----

First, compile:

    make
    
For example, these commands should finish instantly:

    ./fluxcapacitor --libpath=. -- sleep 1
    ./fluxcapacitor --libpath=. -- python -c "import time; time.sleep(1000)"


How does it work
----

Fluxcapacitor does two things:

1) It forces `fluxcapacitor_preload.so` to be preloaded for the
executed command. This library is responsible for two things:
   - It makes sure that `clock_gettime` will not be used by fast VDSO
     mechanism, but by the standard system call. (that gives us the
     opportunity to replace the return value of the system call
     later).
   - It replaces various time-related libc functions, like `time()`
     and `gettimeofday()` with replacements using `clock_gettime`
     underneath.

2) It runs the command (and its forked children) in a `ptrace()`
sandbox, capturing all the syscalls. Some syscalls - notably
`clock_gettime` will have original results overwritten by faked
values. Other syscalls, like `select()`, `poll()` and `epoll_wait()`<commit_msg>More docs<commit_after>Fluxcapacitor
----

Fluxcapacitor is a tool for Linux, created to speed up tests.

It is somewhat similar to tools like:

 * [FreezeGun](http://stevepulec.com/freezegun/) for Python
 * [timecop](https://github.com/travisjeffery/timecop) or
   [Delorean](https://github.com/bebanjo/delorean) for Ruby

These tools patch/mock time libraries in a programming
language.

Fluxcapacitor on the other hand "patches" low-level syscalls. That way
it can lie about time to any program in any programming language, as
long as it runs on Linux.

This approach a significant advantage: it is possible to lie about
time to more than a one processes at the same time. It is especially
useful for testing network applications where server and client run in
different processess (and somewhat rely on time).

Internally Fluxcapacitor relies on `ptrace` syscall and `LD_PRELOAD`
linker feature, and thus is very Linux-specific.


Basic examples
----

First, compile:

    make

For example, these commands should finish instantly:

    ./fluxcapacitor --libpath=. -- sleep 1
    ./fluxcapacitor --libpath=. -- python -c "import time; time.sleep(1000)"


How does it work
----

Fluxcapacitor does two things:

1) It forces `fluxcapacitor_preload.so` to be preloaded for the
executed command. This library is responsible for two things:
   - It makes sure that `clock_gettime` will not be used by fast VDSO
     mechanism, but by the standard system call. (that gives us the
     opportunity to replace the return value of the system call
     later).
   - It replaces various time-related libc functions, like `time()`
     and `gettimeofday()` with replacements using `clock_gettime`
     underneath.

2) It runs the command (and its forked children) in a `ptrace()`
sandbox, capturing all the syscalls. Some syscalls - notably
`clock_gettime` will have original results overwritten by faked
values. Other syscalls, like `select()`, `poll()` and `epoll_wait()`
{'fraction_non_alphanumeric': 0.0820070137577556, 'fraction_numerical': 0.0037766387914755866, 'mean_word_length': 3.944, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3762842', 'n_tokens_mistral': 1110, 'n_tokens_neox': 1046, 'n_words': 470}