libfastcommon: the C utility layer FastDFS was built on

A utility layer extracted from a distributed storage project

libfastcommon is the shared C function library pulled out of happyfish100's FastDFS and FastDHT projects. The description calls it very simple and stable, and the README repeats that the library was extracted from those open source projects.

The origin explains the shape of the API. Almost everything here was written to solve a problem inside a distributed file storage system: non blocking network IO, timeouts measured in thousands of connections, log files that must not block the write path, and configuration files that a cluster of processes reads at startup. That is why the component list runs from a logger and an ini file reader through to a time wheel timer and a scheduler thread.

Some of these functions are also wrapped into a PHP extension, and the README names them: `fastcommon_gethostaddrs`, `fastcommon_id_generator_xxx`, `fastcommon_get_ifconfigs` and `fastcommon_get_sysinfo`. The `php-fastcommon/` directory in the repository layout is where that binding lives. So the audience is wider than embedded C developers: PHP teams that want host address, interface and system information helpers can reach the same code through an extension rather than a C API.

The ini reader handles repeated keys and preprocessor style directives

The configuration parser is the component with the most unusual behaviour. It is described in `ini_file_reader.h` as supporting sections marked by `[SectionName]`, and supporting a config item occurring multiple times for multiple values:

    tracker_server = ip1
    tracker_server = ip2

Repeated keys are how you list several tracker servers in a cluster, so the parser keeps all values for a key rather than overwriting.

The second feature is a small directive language. The README lists the directives and the control statements:

  #include directive to include other ini file
  #@function directive for annotation
  #@set directive to set variables for condition of #@if directive
  support control statements for special purpose as:
    #@if, #@else, #@endif, #@for, #@endfor

That means one configuration file can include another, annotate entries, set a variable, and branch or loop on it. For a system where different hosts in a cluster need different settings, this is the difference between editing one file per node and keeping a shared template. The README points to `doc/ini_file_reader-Chinese.md` for the full guide, which is worth noting because the detailed documentation for this library is partly in Chinese.

A time wheel for network timeouts and an epoll style event loop

Two components handle IO timing. `fast_timer.h` is described as a time wheel based timer for network timeout management, with the README calling it very high performance, and `ioevent.h` plus `ioevent_loop.h` provide an event mechanism described as like epoll that supports Linux, FreeBSD and SunOS.

The mechanism behind a time wheel is worth spelling out, because it explains why a library would include one at all. A timer wheel keeps expiry slots around a ring rather than one queue entry per pending timeout, so inserting and cancelling a timeout is an operation on a bucket. For a server holding a large number of connections where most idle, that is a different cost profile from walking a sorted list or heap of deadlines on every tick.

The event loop sits on top and handles readiness for many sockets, while `sockopt.h` wraps connect, recv and send with IPv6 support, and `fast_task_queue.h` handles network IO buffer management. The library therefore covers the whole path a network server needs: readiness, buffering, deadlines and the timeout decisions that follow.

Memory pools, object allocators and a connection pool

Three allocation related headers sit next to each other in the component list. `fast_mpool.h` is a memory pool, `fast_mblock.h` is an object based allocator, and `connection_pool.h` is a connection pool.

The distinction is scale of object. A memory pool hands out blocks from a larger reserved region, an object allocator manages fixed size object instances with free lists, and a connection pool manages reusable connections rather than memory. They are separate headers because they solve different problems, and mixing them up is the kind of thing that shows up as either fragmentation or as an exhausted pool under bursty load.

Elsewhere in the list there is a hash table in `hash.h`, a singly linked list in `chain.h`, an AVL tree in `avl_tree.h`, a blocked queue in `fast_blocked_queue.h`, and three skiplist variants: `skiplist.h`, `flat_skiplist.h` and `multi_skiplist.h`. The AVL tree and the skiplists are both ordered structures, which tells you the library was written to hold index data structures rather than general purpose collections.

There is also an identifier generator in `id_generator.h`, described as generating unique 64 bit integer IDs for multiple processes, with its own document at `doc/id_generator-Chinese.md`. Multi process uniqueness is the constraint that rules out a naive counter.

Building from source, and what the repository ships

The README does not give an install command, so the build surface is what the repository layout shows. At the top level there is an `INSTALL` file, a `make.sh` script, a `debian/` directory for Debian packaging and `libfastcommon.spec`, which is a spec file for building an RPM. The source itself lives in `src/`, with documentation under `doc/` and the PHP extension under `php-fastcommon/`.

So there are two supported paths in practice: compile the C sources with the provided `make.sh` on a system where you manage your own build, or install a packaged build through the Debian or RPM recipes. The `HISTORY` file at the top level is the changelog.

The library is documented by its headers rather than by prose. The README closes with a note that more detail information can be found in the C header files, and every component in the list is introduced with its header name in square brackets. That is a workable convention for a C library, and it is also the honest limit of the documentation: there is no API guide, no tutorial and no upgrade note beyond the HISTORY file.

The header file names are stable enough to search for, which is the practical way to find a function: look up the component you need in the README list, then open the matching header.

Where a C utility library is the wrong choice

There are clear cases for stepping away. The library is C, so a C++ or Go or Rust codebase cannot use it directly, and no bindings for those languages are described. The public API surface is thin on prose, so for anything beyond the component list you are reading source. The packaged builds cover Debian and RPM style systems, which leaves other distributions without a documented route.

There is also a functional boundary worth stating plainly. A time wheel timer and an epoll style loop are the kind of infrastructure you adopt when you are writing a network server in C yourself. If your work is a web service that already has an HTTP framework, an event loop and a logging configuration file, this library solves problems you do not have. The PHP extension route is the escape hatch for that case, since it exposes a subset of the functions to PHP without asking you to write C.

A second limit is the one the project states about itself: some functions are wrappers around others, and the description of the logger calls it a wrapper around asynchronous disk sync for high performance, thread safe, with log rotate, automatic deletion of old log files and log compression. If your requirement is structured logging with tracing or a centralised collector, a dedicated logging library is the better shape of tool, and nothing here offers that.

LGPL-3.0, no GitHub releases, and a September 2026 push

The licence field on the repository says LGPL-3.0, and there is a `LICENSE` file and a `NOTICE` style packaging alongside the Debian and RPM recipes. LGPL obligations attach to how you link, so if you ship this inside a product you need to check your own linking arrangement and honour the terms rather than take the header at face value.

On maintenance, the facts are narrow. The repository has no GitHub releases, so there is no tag stream and no release notes in the usual place; the changelog is the `HISTORY` file inside the repository. The last push was on 2026-09-06. That date is recent enough to show the work has not stopped, but with no tagged releases and a stable C library that changes rarely, the practical upgrade path is a source build you control rather than a dependency bump.

For a team that adopts this, the cost is therefore integration cost, not upgrade churn. You copy or vendor the sources, you read the headers, and you accept that the documentation arrives in a mix of English and Chinese.

Editorial conclusion

Take libfastcommon when you are writing C that needs a non blocking IO event loop, a time wheel for network timeouts, a rotating asynchronous logger or an ini parser with sections and directives, and you would rather vendor a header level library than maintain your own. Skip it if you need a modern C++ API, a supported package for your platform, or a documented API surface, because the project points you at the C headers for detail and publishes no GitHub releases. The licence field on the repository says LGPL-3.0, so check how you link it before shipping a closed product, and note that the last push was on 2026-09-06 with release history kept in the HISTORY file.

Frequently asked questions

Official sources

1. happyfish100/libfastcommon on GitHub
2. Issues
3. License: LGPL-3.0
4. Project website
5. README