facil.io 0.8.x - The C Server Toolbox Library – C STL :)

The facil.io C STL aims to provide C developers with easy-to-use tools to write memory safe and performant programs.

This C Server Toolbox Library Powers a microFramework

The facil.io library is much more than a Web Application Framework and includes core tools and type templates that any C (and C++) project will find useful.

In addition to useful helpers, facil.io allows developers to use MACROS to generate code for different common types, such as Hash Maps, Arrays, Binary-Safe Strings, etc'.

In other words, some of the most common building blocks one would need in any C project are placed in this convenient header file library.

Installing

Simply copy the fio-stl.h file to your project's folder (using a single header file). Done.

Or... copy the fio-stl folder to your project's folder (using "fio-stl/include.h"). Done.

Include the file as many times as required and enjoy.

Running Tests

To test the STL locally you need to first fork the project or download the whole project source code. Then, from the project's root folder run:

make tests       # run all fast correctness tests

The test suite is split into three categories:

• make tests — fast, deterministic correctness tests. These must pass on every PR.
• make benchmarks — performance benchmarks and library-level comparisons. Run on request.
• make stress — long-running, multi-process, network, or audit tests. Run on request.
• make test-all — run correctness tests, benchmarks, and stress tests in one go.

Individual units can be run with the folder prefix:

make tests/malloc      # memory allocator correctness test
make tests/json        # JSON parser correctness test
make tests/redis       # RESP/Redis helper correctness test
make benchmarks/crypto # crypto performance benchmark
make stress/ipc        # IPC multi-process stress test

Debug builds are available with the db/ prefix, e.g. make tests/json/db.

It is possible to use the same makefile to compile source code and static library code. See the makefile for details.

Quick Examples

There are a number of examples in the ./examples folder, including:

Examples for authoring network applications:

• Mix an HTTP/1.1 Server to serve data with a WebSockets/SSE Chat Server.
• A simple network client example.
• Pub/Sub based TCP/IP text Chat server.

Examples using the C Server Toolbox Library (STL) Types:

• Creating your own Array type.
• Using the included copy-on-write Binary Safe Strings (bstr).
• Making your own reference-counted shared (binary safe) String type.
• using FIOBJ types with JSON for soft / mix typed data structures.
• Authoring your own Hash Maps for your own types.

Running the example code

Examples can be compiled and executed using:

make examples/<name>

For example, to compile and run the server example, use:

make examples/server

Contribution Notice

If you're submitting a PR, make sure to update the corresponding code slice (file) in the fio-stl folder, the makefile will re-produce the fio-stl.h file automatically.

Note that the master branch is currently as unstable as it gets. Commits may get squashed, the branch may be overwritten (force push), etc'. I will play nicer when the code stabilizes.

Also, contributions are subject to the terms and conditions set in the facil.io contribution guide.

Logo contributed by (Area55) under a Creative Commons Attribution 4.0 International License..

Documentation

Documentation is available in the (auto-generated) fio-stl.md file.

Naming Conventions

• snake_case

• Namespace prefix: All public APIs use fio_ prefix (e.g., fio_io_start, fio_subscribe)

• Internal functions: Use fio___ triple underscore for internal/private functions

• Type naming:

  • Structs: <name>_s suffix (e.g., fio_io_s, fio_msg_s)
  • Enums: <name>_e suffix
  • No _t suffix (reserved for POSIX)

• Function naming:

  • <namespace>_<verb> pattern (e.g., fio_io_attach_fd, fio_pubsub_attach)
  • Named arguments pattern: Variadic macros with struct initialization #define fio_io_listen(...) fio_io_listen((fio_io_listen_args_s){__VA_ARGS__})
  • Argument structs: _args_s suffix (e.g., fio_subscribe_args_s)
  • Property naming (getter / setter): <namespace>_<property>(_set) pattern (e.g., fio_bstr_len, fio_bstr_len_set) The setter functions SHOULD return the value that was set, unless it requires memory allocations or causes other performance issues (i.e., when the inner representation doesn't much the setter input).
  • Data retrieval: <namespace>_<property>_get - avoid - implies non-trivial data retrieval with possible side effects.
  • Use object_new/object_free for heap allocations and object_init/object_destroy for supporting stack allocations. the object_destroy should re-initialize memory.

• Function Parameters / Arguments:

  • If parameters have possible defaults, use named arguments pattern.
  • "target" or "destination" parameter should be first (i.e., when writing to a buffer).
  • If a this style parameter exists it MUST ALWAYS be first (then a target parameter, if exists).

Error Handling

• Return values:
  • Pointers: NULL on error
  • Integers: -1 on error, 0 on success
  • Boolean: 0 for false, non-zero for true