The circuit runtime can be instrumented with custom circuit modules that leverage visibility into the circuit's workings to implement application-facing APIs for various special tasks—much like a kernel module would in Linux e.g. Circuit modules are essentially Go packages that can be linked into the circuit runtime.
The circuit source follows a convention for incorporating modules, in order to decouple specific implementations from interfaces. APIs to modular functionalities are placed in packages
circuit/use. These API-packages are the endpoints to be utilized by application code. However, they merely act as proxies to other packages that implement the APIs. This allows one to write application code that depends only on the presence of a given API, but not on its specific implementation in any given circuit runtime configuration.
There are three core user-visible APIs—there also are modules with no user interfaces—that come implemented with the circuit. (Their package sources are within
circuit/use/circuitis the circuit's core programming API, which is described at length in the programming guide.
circuit/use/anchorfsexposes access to the anchor file system for keeping track of live workers.
circuit/use/workeris mostly intended for internal use. It defines a low-level abstract API for spawning and killing workers, as well as establishing communication with them.
Two additional packages are included, mostly as examples. Package
circuit/use/issuefs is a programmatic API to an issue tracking system. And package
circuit/use/durablefs is an experimental persistent file system, backed by Zookeeper, for storing Go types that may contain circuit-specific subtypes like cross-interfaces.
All APIs are documented within the
godoc documentation system.
The command-line toolkit of the circuit is a set of commands that facilitate daily interaction with circuit environments. It encompasses building, debugging, profiling, maintnance and operation.
All toolkit commands are implemented as descendants to package
circuit/cmd. Respectively, their detailed and up-to-date documentation should be looked up within the
godoc of the respective package.
We find ourselves using a set of library packages over and over again when we build circuit apps.
We have included the most commonly-used ones as descendants to package
godoc is the best source for these packages.
At high-level, the miscellaneous libraries kit includes things like scheduling abstractions like
circuit/kit/sched/limiter, consistent-hashing algorithms
circuit/kit/xor, file system abstractions often used for isolation or integration, data structures like
circuit/kit/llrb, statistics, Zookeeper usability tools, etc.
Once the Go Circuit is installed and is in your
you can view the API documentation the same way you view Go's documentation itself.
Simply run the Go documentation server:
% godoc -http=:6060
And point your browser to
This will give you the table-of-contents of all packages currently available on
your system. Locate the
circuit packages and read on.
Alternatively, you can read the Go documentation of any package on the command-line, with queries like
% godoc circuit | less