A project by Petar Maymounkov.

Modules, APIs and command-line toolkit


Modules and their APIs

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 descendant to 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/sys/….)

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.

Command-line toolkit

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.

Miscellaneous libraries

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 circuit/kit. The 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.

The documentation server

Once the Go Circuit is installed and is in your GOPATH, 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 localhost:6060/pkg. 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