circuit: github.com/gocircuit/circuit/client Index | Files | Directories

package client

import "github.com/gocircuit/circuit/client"

Package client provides access to the circuit programming environment to user programs.

Index

Package Files

chan.go client.go dns.go proc.go server.go subscription.go term.go

Constants

const (
    Running   = "running"
    Exited    = "exited"
    Stopped   = "stopped"
    Signaled  = "signaled"
    Continued = "continued"
    Unknown   = "unknown"
)

func Split Uses

func Split(walk string) (r []string)

Split breaks up an anchor path into components.

type Anchor Uses

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 Uses

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 Uses

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 Uses

type Client struct {
    // contains filtered or unexported fields
}

Client is a live session with a circuit server.

func Dial Uses

func Dial(addr string, authkey []byte) *Client

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 Uses

func DialDiscover(multicast string, authkey []byte) *Client

func (*Client) Addr Uses

func (c *Client) Addr() string

Address returns the circuit address of the server that this client is connected to.

func (*Client) Get Uses

func (c *Client) Get() interface{}

Get is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeChan Uses

func (c *Client) MakeChan(n int) (Chan, error)

MakeChan is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeDocker Uses

func (c *Client) MakeDocker(run docker.Run) (docker.Container, error)

MakeDocker is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeNameserver Uses

func (c *Client) MakeNameserver(string) (Nameserver, error)

MakeNameserver…

func (*Client) MakeOnJoin Uses

func (c *Client) MakeOnJoin() (Subscription, error)

MakeOnJoin is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeOnLeave Uses

func (c *Client) MakeOnLeave() (Subscription, error)

MakeOnLeave is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeProc Uses

func (c *Client) MakeProc(cmd Cmd) (Proc, error)

MakeProc is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) Path Uses

func (c *Client) Path() string

func (*Client) Scrub Uses

func (c *Client) Scrub()

Scrub is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) ServerID Uses

func (c *Client) ServerID() string

ServerID returns the server ID of the circuit server that this client is connected to.

func (*Client) View Uses

func (c *Client) View() map[string]Anchor

View returns a map of all currently-live circuit server anchors. Errors in communication are reported as panics.

func (*Client) Walk Uses

func (c *Client) Walk(walk []string) Anchor

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

type ServerStat struct {
    Addr   string
    Joined time.Time
}

ServerStat encloses subscription state information.

type Subscription Uses

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 Uses

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.

Directories

PathSynopsis
docker

Package client imports 22 packages (graph) and is imported by 5 packages. Updated 2016-07-19. Refresh now. Tools for package owners.