Documentation ¶
Overview ¶
Package client provides access to the circuit programming environment to user programs.
Index ¶
- Constants
- func Split(walk string) (r []string)
- type Anchor
- type Chan
- type ChanStat
- type Client
- func (c *Client) Addr() string
- func (c *Client) Get() interface{}
- func (c *Client) MakeChan(n int) (Chan, error)
- func (c *Client) MakeDocker(run docker.Run) (docker.Container, error)
- func (c *Client) MakeNameserver(string) (Nameserver, error)
- func (c *Client) MakeOnJoin() (Subscription, error)
- func (c *Client) MakeOnLeave() (Subscription, error)
- func (c *Client) MakeProc(cmd Cmd) (Proc, error)
- func (c *Client) Path() string
- func (c *Client) Scrub()
- func (c *Client) ServerID() string
- func (c *Client) View() map[string]Anchor
- func (c *Client) Walk(walk []string) Anchor
- type Cmd
- type Nameserver
- type NameserverStat
- type Proc
- type ProcStat
- type Server
- type ServerStat
- type Subscription
- type SubscriptionStat
Constants ¶
const ( Running = "running" Exited = "exited" Stopped = "stopped" Signaled = "signaled" Continued = "continued" Unknown = "unknown" )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Anchor ¶
type Anchor interface { // Addr returns the address of the circuit server hosting this anchor. Addr() string // ServerID returns the ID of the circuit server hosting this anchor. // The returned string will look like "X123..." ServerID() string // Walk traverses the anchor namespace, starting from this anchor along the path in walk. // Errors in communication or a missing circuit server condition are reported via panics. Walk(walk []string) Anchor // View returns the set of this anchor's sub-anchors. View() map[string]Anchor // MakeChan creates a new circuit channel element at this anchor with a given capacity n. // If the anchor already stores an element, a non-nil error is returned. // Panics indicate that the server hosting the anchor is gone. MakeChan(n int) (Chan, error) // MakeProc issues the execution of an OS process, described by cmd, at the server hosting the anchor // and creates a corresponding circuit process element at this anchor. // If the anchor already stores an element, a non-nil error is returned. // Panics indicate that the server hosting the anchor is gone. MakeProc(cmd Cmd) (Proc, error) // MakeDocker… MakeDocker(run cdocker.Run) (cdocker.Container, error) // MakeNameserver… MakeNameserver(addr string) (Nameserver, error) // MakeOnJoin… MakeOnJoin() (Subscription, error) // MakeOnLeave… MakeOnLeave() (Subscription, error) // Get returns a handle for the circuit element (Chan, Proc, Subscription, Server, etc) // stored at this anchor, and nil otherwise. // Panics indicate that the server hosting the anchor and its element has already died. Get() interface{} // Scrub aborts and abandons the circuit element stored at this anchor, if one is present. // If the hosting server is dead, a panic will be issued. Scrub() // Path returns the path to this anchor Path() string }
An Anchor represents a location in the global anchor namespace of a circuit cluster. Anchors are named locations where the user can store and operate control primitives, called circuit elements. The anchor namespace hierarchy is represented in paths of the form
/X8817c114d4941522/hello/dolly
The root anchor "/" represents the cluster abstractly and is the only anchor within which one cannot create elements or freely-named subanchors. The root anchor contains a dynamically changing set of sub-anchors that correspond to the live circuit servers in the cluster.
Every anchor, other than "/", can be used to make, store and operate a circuit element (a process or a channel). Anchors are created on access, if not present, and are garbage-collected when not used or referenced. Therefore the interface allows users to access arbitrary paths without having to create them first.
type Chan ¶
type Chan interface { // Send blocks until the requested transmission is matched to a receiving call to Recv, or // until it can be accommodated in the channel's buffer. // It returns a WriteCloser representing a byte pipe to the receiver, or a non-nil error // if the channel has already been closed. Send() (io.WriteCloser, error) // Scrub aborts and abandons the channel. Any buffered send operations are lost. Scrub() // Close closes the channel, reporting an error only if the channel has already been closed. Close() error // Recv blocks until it can be matched with a sender. // It returns a ReadCloser for the byte pipe from the sender, or a non-nil error if the // channel has been closed. Recv() (io.ReadCloser, error) // Cap reports the capacity of the channel. Cap() int // Stat returns the current state of the channel. Stat() ChanStat }
Chan provides access to a circuit channel element.
A channel element is semantically identical to a Go channel, with the sole exception that the "messages" passed through the channel are pipes that connect the sender and the receiver and allow them, once connected, to exchange an arbitrary stream of byte data which as a whole counts as one channel message.
All methods panic if the server hosting the channel dies.
type ChanStat ¶
type ChanStat struct { // Cap is the channel capacity. Cap int // Closed is set as soon as Close is called. // If Closed is set, the channel might still have messages in its buffer and // thus its receive side remains operational. Closed bool // Aborted is set if the channel has been permanently aborted and is not usable any longer. Aborted bool // NumSend is the number of completed invocations to Send. NumSend int // NumRecv is the number of completed invocations to Recv. NumRecv int }
ChanStat describes the state of a channel.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a live session with a circuit server.
func Dial ¶
Dial establishes a connection to a circuit server specified by a circuit address. Circuit addresses are printed to standard output when a server is started with the "circuit start …" command.
If authkey is non-nil it is used as a private key and all communications are secured by HMAC authentication and RC4 symmetric encryption; otherwise transmissions are in plaintext.
Errors in communication, such as a missing server, or invalid URL format are reported through panics.
func DialDiscover ¶
func (*Client) Addr ¶
Address returns the circuit address of the server that this client is connected to.
func (*Client) Get ¶
func (c *Client) Get() interface{}
Get is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) MakeChan ¶
MakeChan is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) MakeDocker ¶
MakeDocker is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) MakeNameserver ¶
func (c *Client) MakeNameserver(string) (Nameserver, error)
MakeNameserver…
func (*Client) MakeOnJoin ¶
func (c *Client) MakeOnJoin() (Subscription, error)
MakeOnJoin is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) MakeOnLeave ¶
func (c *Client) MakeOnLeave() (Subscription, error)
MakeOnLeave is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) MakeProc ¶
MakeProc is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) Scrub ¶
func (c *Client) Scrub()
Scrub is an Anchor interface method, not applicable to the root-level anchor.
func (*Client) ServerID ¶
ServerID returns the server ID of the circuit server that this client is connected to.
func (*Client) View ¶
View returns a map of all currently-live circuit server anchors. Errors in communication are reported as panics.
func (*Client) Walk ¶
Walk traverses the global virtual anchor namespace and returns a handle to the desired anchor. The first element of walk should be the ID of a live circuit server. An up to date list of available circuit servers in the cluster can be obtained by calling View. The remainder of the walk slice is up to the user. Errors in communication or missing servers are reported as panics.
type Cmd ¶
type Cmd struct { // Env, if set, is the desired OS execution environment. It corresponds to Cmd.Env from package "os/exec". Env []string // Dir, if non-empty, is the working directory for the process. Dir string // Path is the local file-system path, at the respective circuit server, to the process binary. Path string // Args is a list of command line arguments to be passed on to the process. // The first element in the slice corresponds to the first argument to the process (not to its binary path). Args []string // If Scrub is set, the process element will automatically be removed from its anchor // when the process exits. Scrub bool }
Cmd describes the execution parameters for an OS process.
type Nameserver ¶
type Nameserver interface { Set(rr string) error Unset(name string) // Peek asynchronously returns the current state of the server. Peek() NameserverStat // Scrub shuts down the nameserver and removes its circuit element. Scrub() }
type NameserverStat ¶
type NameserverStat struct { // IP address of the nameserver Address string // Resource records resolved by this nameserver Records map[string][]string }
NameserverStat encloses process state information.
type Proc ¶
type Proc interface { // Wait blocks until the underlying OS process exits and returns the final status of the process. // An error is returned only if the wait invocation is aborted by a concurring call to Scrub. Wait() (ProcStat, error) // Signal sends an OS signal to the process. The following are recognized signal names: // ABRT, ALRM, BUS, CHLD, CONT, FPE, HUP, ILL, INT, IO, IOT, KILL, PIPE, // PROF, QUIT, SEGV, STOP, SYS, TERM, TRAP, TSTP, TTIN, TTOU, URG, USR1, // USR2, VTALRM, WINCH, XCPU, XFSZ. Signal(sig string) error // GetEnv returns the environment at the hosting server OS. GetEnv() []string // GetCmd returns the command that started this process. GetCmd() Cmd // Peek asynchronously returns the current state of the process. Peek() ProcStat // Scrub abandons the circuit process element, without affecting the underlying OS process. Scrub() // Stdin returns a WriterCloser to the standard input of the underlying OS process. // The user is responsible for closing the standard input, even if they do not // intend to write to it. Stdin() io.WriteCloser // Stdout returns the standard output of the underlying OS process. Stdout() io.ReadCloser // Stderr returns the standard error of the underlying OS process. Stderr() io.ReadCloser }
Proc provides access to a circuit process element. All methods panic if the hosting circuit server dies.
type ProcStat ¶
type ProcStat struct { // Cmd is a copy of the command that started the process. Cmd Cmd // Error will be non-nil if the process has already exited in error. Exit error // Phase describes the current state of the process. // Its possible values are Running, Exited, Stopped, Signaled, Continued and Unknown. Phase string }
ProcStat encloses process state information.
type Server ¶
type Server interface { Profile(string) (io.ReadCloser, error) Peek() ServerStat Rejoin(string) error Suicide() }
Server… All methods panic if the hosting circuit server dies.
type ServerStat ¶
ServerStat encloses subscription state information.
type Subscription ¶
type Subscription interface { // Consume blocks until the next message is available on the channel. Consume() (interface{}, bool) // Peek asynchronously returns the current state of the process. Peek() SubscriptionStat // Scrub abandons the circuit process element, without affecting the underlying OS process. Scrub() }
Subscription provides access to a circuit subscription element. All methods panic if the hosting circuit server dies.
type SubscriptionStat ¶
type SubscriptionStat struct { // Name of event source Source string // Pending equals the number of messages waiting to be consumed. Pending int // Closed is true if the publisher stream has marked an end. Closed bool }
SubscriptionStat encloses subscription state information.