odo - an atomic odometer for the command line
Atomic Odometer? What?
odo atomically updates a count in a file, which will be created if not present. The count is text-formatted (e.g. "00012345\n"), and will be accurately incremented or reset even when multiple processes attempt to change the counter at the same time. (It uses memory mapping and atomic compare-and-swap operations to eliminate race conditions.)
This could be used to track some intermittent event, like services being restarted. (This was the original inspiration.) Since the counter is just a number in a text file, it's easy to compose odo with other tools.
odo depends on atomic compare-and-swap functionality (e.g.
__sync_bool_compare_and_swap), which is available on most common
platforms. The build is currently tested on Linux, OpenBSD, and OSX on
x86 and x86-64 systems, as well as on a Raspberry Pi (32-bit ARM).
If the gcc-specific feature defines in
types.h are not recognized by
your C99 compiler, you may need to set
COUNTER_SIZE in the Makefile
-DCOUNTER_SIZE=4 for 32-bit systems and
for 64-bit systems.
To build it, just type:
To install it:
$ make install
To run the tests:
$ make test
This atomically increments a counter in /log/restarts. If the counter file does not exist, it is created as 0 and incremented to 1.
$ odo /log/restarts
Same, but print the updated count:
$ odo -p /log/restarts
Reset the count to 0:
$ odo -r /log/restarts
Set the count to a number (for testing notifications, perhaps):
$ odo -s 12345 /log/restarts
Print the current counter value without incrementing:
$ odo -c /log/restarts
Print usage / help:
$ odo -h
odo's atomicity is only as reliable as the underlying filesystem's. Inconsistencies may still occur if used on a non-local filesystems such as nfs.