Navigating and using the anchor hierarchy

As you as obtain a *Client object after dialing, you have your hands on the root anchor. The type *Client implements the Anchor interface.

Anchors have two sets of methods: Those for navigating the anchor hierarchy and those for manipulating elements attached to the anchor. We'll examine both types in turn.

In general, it is safe to call all methods of anchor objects concurrently. In other words, you can use the same anchor object from different goroutines without any synchronization.

Navigating

Anchors have two methods pertaining to navigation of the anchor hierarchy:

	View() map[string]Anchor
	Walk(walk []string) Anchor

Method View will return the current list of subanchors of this anchor. The result comes in the form of a map from child names to anchor objects.

Method Walk takes one []string argument walk, which is interpreted as a relative path (down the anchor hierarchy) from this anchor to a descendant. Walk traverses the path and returns the descendant anchor, separated from this one by the path walk.

Note that Walk always succeeds: If a child anchor is missing as Walk traverses down the hierarchy, the anchor is created automatically. Anchors persist within the circuit cluster as long as they are being used, otherwise they are garbage-collected. An anchor is in use if at least one of the following conditions is met:

It is being used by a client (in the form of a held Anchor object),
It has an element attached to it (something like a process or a container, for example), or
It has child anchors.

In other words, Walk is not only a method for accessing existing anchors but also a method for creating new ones (should they not already exist).

The only exception to this rule is posed at the root anchor. The root anchor logically corresponds to the cluster as a whole. The only allowed subanchors of the root anchor are the ones corresponding to available circuit servers, and these anchors are created and removed automatically by the system.

If Walk is invoked at the root anchor with a path argument, whose first element is not present in the hierarchy, the invokation will panic to indicate an error. This is not a critical panic and one can safely recover from it and continue.

Manipulating elements

The Anchor interface has a set of Make… methods, each of which creates a new resource (process, container, etc.) and, if successful, atomically attaches it to the anchor. (These methods would fail with a non-nil error, if the anchor already has an element attached to it.)

	MakeChan(int) (Chan, error)
	MakeProc(Cmd) (Proc, error)
	MakeDocker(cdocker.Run) (cdocker.Container, error)
	MakeNameserver(string) (Nameserver, error)
	MakeOnJoin() (Subscription, error)
	MakeOnLeave() (Subscription, error)

The use of these methods is detailed in the following sections, dedicated to processes, containers, channels, name servers and subscriptions.

Anchors have two generic methods for manipulating elements as well:

	Get() interface{}
	Scrub()

The Get method will return the element currently associated with the anchor. (This would be an object of type Chan, Proc, Container, Nameserver, Server or Subscription.)

The Scrub method will terminate the operation of the element attached to this anchor and will remove the element from the anchor.

Auxiliary methods

Anchors have a couple of auxiliary methods to facilitate programming:

	Addr() string
	Path() string

The method Addr returns the circuit address of the server that is hosting this anchor. The returned value would be a string of the form circuit://….

The method Path will return the file-system notation of the anchor's path. This would be a string looking like "/X50faec8c2b5f6418/mysql/shard/1", for instance.