corosync synchronises cluster state through four registered events

The cluster engine, and the problem its services share

corosync is described in one line as the Corosync Cluster Engine, and the repository is C with autotools packaging, but what the documentation actually explains is the part that every service in the system has to get right. The engine runs a ring of processors, and the ring changes shape when the network partitions or merges, because a partition splits the ring into segments and a merge puts them back together. Every service therefore has to agree on state with every other service, and it has to do so at moments when messages may be lost, delayed or duplicated. The synchronization algorithm described in the README is the contract that makes this tractable. It is a set of four events, and the documentation is careful to say that these events are in fact functions registered in the service handler data structure, called by the synchronization system whenever a network partitions or merges. The audience is anyone writing a service for the engine, and the audience for the code itself is cluster software in general.

init, process, abort and activate, and what each one owes the engine

The four events divide the work cleanly. In the init event, a service handler records the temporary state variables it will need during the process event, and the checkpoint implementation uses this to enter its first state. The process event executes the synchronization itself and returns a state saying whether it has completed, which is the mechanism that lets a synchronization be interrupted and continued later. The abort event happens when a processor failure occurs during synchronization, and its job is to release everything temporary, freeing all temporary checkpoints and temporary sections. The activate event fires when process has reported that no more processing is necessary for any node in the cluster and all messages originated by process have completed, and that is when the temporary state becomes real: previously committed checkpoints and sections are freed, temporary checkpoints and sections are converted to regular sections, and the saved ring id is copied to the old ring id. The ordering is the whole design, and a service that gets activate wrong leaves a cluster with state that looks committed but was never agreed on.

The process event returns, and that is what makes sync resumable

The detail that distinguishes this design from a simple broadcast is that process is not a one-shot function. It returns a state as to whether it has completed or not, and the synchronization system calls it again if the return variable asks for that. The stated reason is that the message queue buffer can fill up, so a service cannot always finish in one pass, and a design that assumed it could would either block the engine or lose work. In the checkpoint algorithm the same pattern appears as a requirement that process continue or that process not continue, and in both cases the service records its current iteration state when it cannot proceed, so that the next invocation resumes where it stopped rather than starting over. The pseudocode for the checkpoint state machine shows both branches:

if all checkpoints and sections could be queued
	call sync_refcounts_enter
else
	record my_current_iteration_state

require process to continue

The pattern of returning a continuation request and saving progress state is what a service handler has to implement, and it is the part most likely to be implemented incorrectly by a new service author, because a service that always returns complete will appear to work until the message queue fills under load.

Checkpoint synchronization runs in two states

The checkpoint algorithm has a specific purpose. It synchronizes checkpoints after a partition or merge of two or more partitions, and its secondary purpose is to determine the cluster-wide reference count for every checkpoint. The data model is simple. Every cluster contains a group of checkpoints, and each checkpoint has a name and a number, the number being what uniquely references an unlinked but still open checkpoint in the cluster. Every checkpoint also carries a reference count, used to determine when the checkpoint may be released, and the algorithm rebuilds that reference count information each time a partition or merge occurs. The local variables show the two states the processor moves through, my_sync_state may be SYNC_CHECKPOINT or SYNC_REFCOUNT, and my_current_iteration_state holds the data used to iterate the checkpoints and sections. The entry point sets the state to SYNC_CHECKPOINT and points the iteration at the start of the checkpoint list, and the transition into the second state happens only once all checkpoints and sections could be queued.

Only the lowest processor id in the old ring transmits

The transmission rule is what stops every node from repeating the same work. In the SYNC_CHECKPOINT state, the pseudocode says that if the lowest processor identifier of the old ring is in the new ring, it transmits checkpoints or sections starting from the saved iteration state. The same condition governs the SYNC_REFCOUNT state, where that processor transmits the checkpoint reference counts. Elsewhere the algorithm explicitly ignores a foreign ring id message, and a checkpoint update that finds the checkpoint already in temporary storage is ignored, as is a section update whose section already exists, so duplicate deliveries are absorbed rather than applied twice. A reference count update is different, since it adds the reference counts in the temporary message set to those already stored and then updates the checkpoint's own count, and it advances the global checkpoint id if it would increase. The global count and the per-node sets are kept separately, which is why the reference count for a checkpoint is described as a summation over a set that pairs the number of opened connections with the node identifier.

Autotools packaging, annual point releases and a custom licence

The build system is the classic autotools layout, with configure.ac, Makefile.am, autogen.sh, an INSTALL file, build-aux/, a pkgconfig/ directory and a corosync.spec.in for packaging. The source tree is laid out the way a C project of this kind usually is, with common_lib/, lib/, include/, exec/ for the executors, bindings/ for the language bindings, tools/, test/, man/ for the manual pages, loc/ for localisation, and vqsim/, which the name suggests is a simulator for the vote quorum logic. There is a Doxyfile.in for documentation generation, a.clang-format file, and a.gitarchivever file, which is the mechanism for embedding a version derived from the git archive into the build. The licence is the item to check first. It is not one of the identifiers GitHub can classify, so you have to read the LICENSE file to know what you are agreeing to, and the README gives no terms at all. On maintenance, the tagged releases are annual point releases, v3.1.8 on 2023-11-15, v3.1.9 on 2024-11-15 and v3.1.10 on 2025-11-15, while the last push was on 2026-09-17, so the tree moves between releases rather than during them.

Editorial conclusion

corosync is a project to read when you are writing or debugging a cluster service, because the synchronization contract in its documentation is precise enough to implement against, and the checkpoint algorithm explains how a cluster rebuilds reference counts after a partition without guessing. It is not a project to adopt as a general dependency without checking terms, since the licence is a custom one that GitHub cannot classify and you need to read the LICENSE file yourself,, and the tagged releases are annual point releases, though the source tree keeps moving between them. Before evaluating it, read the LICENSE file, check the configure options for your target platform, and plan to build it from source rather than expecting a package that matches your distribution.

Frequently asked questions

Official sources

1. corosync/corosync on GitHub
2. Issues
3. Project website
4. README
5. Releases