Unlocking High‑Performance Global IDs and Limits with Coconut

Overview

Coconut is an application‑level cache server that provides two scenario modes: a global sequence ID generator and a global limit manager, both designed as high‑performance, lock‑free components for distributed or clustered architectures.

Global Sequence ID Generator

ID Format

The generated ID consists of 16 base‑64 characters (alphabet: 0‑9, a‑z, A‑Z, -,_). The layout is divided into five zones:

Zone 1 (index) : 2 characters (12 bits) – sub‑fields for reserve, server number, timestamp, and serial number.

Zone 2 (reserve) : 1 character (6 bits) – user‑defined reserve value.

Zone 3 (server_no) : 2 characters – up to 4096 servers.

Zone 4 (secondstamp) : 6 characters – seconds since epoch, covering up to year 2179.

Zone 5 (serial_no) : 5 characters – serial range [1, 1 000 000 000].

Example ID: aR2011o_cWG00002 Decoded fields:

reserve: 2

server_no: 1

secondstamp: 1492962986 (2017‑04‑23 23:56:26)

serial_no: 2

Service Interface

GET /fetch – returns a new global ID (HTTP 200 on success).

GET /explain?sequence=ID – returns a human‑readable breakdown of the ID fields.

Usage Example

$ coconut -M SEQUENCE -l 127.0.0.1 -p 9527 -c 1 --loglevel-warn --reserve 2 --server-no 1

$ curl http://127.0.0.1:9527/fetch

$ curl "http://127.0.0.1:9527/explain?sequence=aR2011o_cWG00002"

Performance Test

Using ApacheBench (ab) with 100 concurrent connections and 100 000 requests:

$ ab -c 100 -n 100000 http://127.0.0.1:9527/fetch

Result: ~41 000 requests/second, average latency 2.44 ms.

Global Limit Manager

The limit manager offers lock‑free APIs for high‑frequency operations on quota‑type resources (query, apply, cancel, increase, decrease, empty).

Service Interface

GET /query – returns remaining quota.

GET /apply?amt=VALUE – allocates quota, returns transaction ID and remaining quota.

GET /cancel?jnlsno=ID – revokes a transaction.

GET /increase?amt=VALUE – adds to total quota.

GET /decrease?amt=VALUE – subtracts from total quota.

GET /empty – resets quota to zero.

Usage Example

$ coconut -M LIMITAMT -l 127.0.0.1 -p 9527 -c 1 --loglevel-warn --limit-amt 1000000 --export-jnls-amt-pathfilename $HOME/coconut_JNLSNO_AMT.txt

$ curl http://127.0.0.1:9527/query

$ curl http://127.0.0.1:9527/apply?amt=11

$ curl http://127.0.0.1:9527/cancel?jnlsno=46

$ curl http://127.0.0.1:9527/increase?amt=1000000

$ curl http://127.0.0.1:9527/decrease?amt=500000

$ curl http://127.0.0.1:9527/empty

Performance Test

Long‑connection benchmark for applying quota:

$ ab -kc 100 -n 1000000 http://127.0.0.1:9527/apply?amt=1

Result: ~295 000 requests/second, average latency 0.34 ms.

Command‑Line Parameters (Appendix A)

Running coconut without arguments prints all options. Key flags: -M SEQUENCE|LIMITAMT – select scenario mode. -l IP – listen address. -p PORT – listen port. -c COUNT – number of worker processes (limit manager supports only one). --reserve VALUE – reserve field for sequence IDs. --server-no VALUE – server identifier. --limit-amt VALUE – total quota for limit manager. --export-jnls-amt-pathfilename PATH – file to export transaction log after quota is exhausted.

References

The full source code is hosted on Gitee (Open Source China) and GitHub. The project also depends on the author’s other open‑source libraries iLOG3, fasterhttp, and tcpdaemon.