https://github.com/atomicobject/odo
an atomic odometer for the command line
https://github.com/atomicobject/odo
Last synced: 7 months ago
JSON representation
an atomic odometer for the command line
- Host: GitHub
- URL: https://github.com/atomicobject/odo
- Owner: atomicobject
- Created: 2014-11-15T14:33:38.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2017-10-22T10:41:43.000Z (over 8 years ago)
- Last Synced: 2025-09-14T06:12:19.060Z (7 months ago)
- Language: C
- Size: 17.6 KB
- Stars: 73
- Watchers: 7
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
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][1] to eliminate race conditions.)
[1]: https://spin.atomicobject.com/2014/11/24/odo-atomic-counters-from-the-command-line/
## Use cases
This could be used to track some intermittent event, like services being
restarted. (This was the [original inspiration][2].) Since the counter
is just a number in a text file, it's easy to compose odo with other
tools.
[2]: https://twitter.com/nrr/status/529016501421240322
## Dependencies
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
yourself: `-DCOUNTER_SIZE=4` for 32-bit systems and `-DCOUNTER_SIZE=8`
for 64-bit systems.
## Getting started
To build it, just type:
$ make
To install it:
$ make install
To run the tests:
$ make test
## Example Use
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
## Note
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.