Back to godoc.org
v.io / v23

Package v23

v0.1.13
Latest Go to latest

The highest tagged major version is .

Published: Oct 21, 2020 | License: BSD-3-Clause | Module: v.io

Overview

Package v23 defines the runtime interface of Vanadium, and its subdirectories define the entire Vanadium public API.

Once Vanadium reaches version 1.0 these public APIs will be stable over an extended period. Changes to APIs will be managed to ensure backwards compatibility, using the same policy as http://golang.org/doc/go1compat.

This is version 0.1 - we will do our best to maintain backwards compatibility, but there's no guarantee until version 1.0.

For more information about the Vanadium project, please visit https://vanadium.github.io.

Index

func GetBackgroundContext

func GetBackgroundContext(ctx *context.T) *context.T

GetBackgroundContext returns a background context. This context can be used for general background activities.

func GetClient

func GetClient(ctx *context.T) rpc.Client

GetClient returns the Client in 'ctx'.

func GetListenSpec

func GetListenSpec(ctx *context.T) rpc.ListenSpec

GetListenSpec returns the ListenSpec in 'ctx'.

func GetNamespace

func GetNamespace(ctx *context.T) namespace.T

GetNamespace returns the Namespace in 'ctx'.

func GetPermissionsSpec

func GetPermissionsSpec(ctx *context.T) access.PermissionsSpec

GetPermissionsSpec returns the Permissions for the specified name in 'ctx'.

func GetPrincipal

func GetPrincipal(ctx *context.T) security.Principal

GetPrincipal returns the Principal in 'ctx'.

func GetReservedNameDispatcher

func GetReservedNameDispatcher(ctx *context.T) rpc.Dispatcher

GetReservedNameDispatcher returns the dispatcher used for reserved names.

func NewDiscovery

func NewDiscovery(ctx *context.T) (discovery.T, error)

NewDiscovery returns a new Discovery.T instance.

func NewFlowManager

func NewFlowManager(ctx *context.T, channelTimeout time.Duration) (flow.Manager, error)

NewFlowManager creates a new flow.Manager instance. channelTimeout specifies the duration we are willing to wait before determining that connections managed by this FlowManager are unhealthy and should be closed.

func RegisterRuntimeFactory

func RegisterRuntimeFactory(f RuntimeFactory)

RegisterRuntimeFactory register the specified RuntimeFactory. It must be called before v23.Init; typically it will be called by an init function. It will panic if called more than once.

func WithListenSpec

func WithListenSpec(ctx *context.T, ls rpc.ListenSpec) *context.T

WithListenSpec attaches a ListenSpec to the returned context.

func WithNewClient

func WithNewClient(ctx *context.T, opts ...rpc.ClientOpt) (*context.T, rpc.Client, error)

WithNewClient creates a new Client instance and attaches it to a new context.

func WithNewDispatchingServer

func WithNewDispatchingServer(ctx *context.T, name string, disp rpc.Dispatcher, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)

WithNewDispatchingServer creates a new flow.Manager instance and attaches it to ctx, and creates a new dispatching server on that flow.Manager.

func WithNewNamespace

func WithNewNamespace(ctx *context.T, roots ...string) (*context.T, namespace.T, error)

WithNewNamespace creates a new Namespace instance and attaches it to the returned context.

func WithNewServer

func WithNewServer(ctx *context.T, name string, object interface{}, auth security.Authorizer, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)

WithNewServer creates a new flow.Manager instance and attaches it to ctx, and creates a new server on that flow.Manager.

func WithPrincipal

func WithPrincipal(ctx *context.T, principal security.Principal) (*context.T, error)

WithPrincipal attaches 'principal' to the returned context.

func WithReservedNameDispatcher

func WithReservedNameDispatcher(ctx *context.T, d rpc.Dispatcher) *context.T

WithReservedNameDispatcher returns a context that uses the provided dispatcher to handle reserved names in particular __debug.

type Runtime

type Runtime interface {
	// Init is a chance to initialize state in the runtime implementation
	// after the runtime has been registered in the v23 package.
	// Code that runs in this routine, unlike the code in the Runtime's
	// constructor, can use the v23.Get/With methods.
	Init(ctx *context.T) error

	// WithPrincipal attaches 'principal' to the returned context.
	WithPrincipal(ctx *context.T, principal security.Principal) (*context.T, error)

	// GetPrincipal returns the Principal in 'ctx'.
	GetPrincipal(ctx *context.T) security.Principal

	// WithNewClient creates a new Client instance and attaches it to a
	// new context.
	WithNewClient(ctx *context.T, opts ...rpc.ClientOpt) (*context.T, rpc.Client, error)

	// GetClient returns the Client in 'ctx'.
	GetClient(ctx *context.T) rpc.Client

	// WithNewNamespace creates a new Namespace instance and attaches it to the
	// returned context.
	WithNewNamespace(ctx *context.T, roots ...string) (*context.T, namespace.T, error)

	// GetNamespace returns the Namespace in 'ctx'.
	GetNamespace(ctx *context.T) namespace.T

	// GetListenSpec returns the ListenSpec in 'ctx'.
	GetListenSpec(ctx *context.T) rpc.ListenSpec

	// WithListenSpec attaches a ListenSpec to the returned context.
	WithListenSpec(ctx *context.T, ls rpc.ListenSpec) *context.T

	// GetPermissionSpec returns the PermissonsSpec stored in 'ctx'.
	GetPermissionsSpec(ctx *context.T) access.PermissionsSpec

	// WithBackgroundContext creates a new context derived from 'ctx'
	// with the given context set as the background context.
	WithBackgroundContext(ctx *context.T) *context.T

	// GetBackgroundContext returns a background context. This context can be used
	// for general background activities.
	GetBackgroundContext(ctx *context.T) *context.T

	// NewDiscovery returns a new Discovery.T instance.
	NewDiscovery(ctx *context.T) (discovery.T, error)

	// WithReservedNameDispatcher returns a context that uses the
	// provided dispatcher to control access to the framework managed
	// portion of the namespace.
	WithReservedNameDispatcher(ctx *context.T, d rpc.Dispatcher) *context.T

	// GetReservedNameDispatcher returns the dispatcher used for
	// reserved names.
	GetReservedNameDispatcher(ctx *context.T) rpc.Dispatcher

	// NewFlowManager creates a new flow.Manager instance.
	// channelTimeout specifies the duration we are willing to wait before determining
	// that connections managed by this FlowManager are unhealthy and should be
	// closed.
	NewFlowManager(ctx *context.T, channelTimeout time.Duration) (flow.Manager, error)

	// WithNewServer creates a new Server instance to serve a service object.
	//
	// The server will listen for network connections as specified by the
	// ListenSpec attached to ctx. Depending on your RuntimeFactory, 'roaming'
	// support may be enabled. In this mode the server will listen for
	// changes in the network configuration using a Stream created on the
	// supplied Publisher and change the set of Endpoints it publishes to
	// the mount table accordingly.
	//
	// The server associates object with name by publishing the address of
	// this server in the namespace under the supplied name and using
	// authorizer to authorize access to it. RPCs invoked on the supplied
	// name will be delivered to methods implemented by the supplied
	// object.  Reflection is used to match requests to the object's
	// method set.  As a special-case, if the object implements the
	// Invoker interface, the Invoker is used to invoke methods directly,
	// without reflection.  If name is an empty string, no attempt will
	// made to publish.
	//
	// WithNewServer will create a new flow.Manager to back the server
	// and return a new context with that flow.Manager attached.  This
	// means that clients who use the returned context will be able to
	// share connections with the server, enabling bidirectional RPC.
	WithNewServer(ctx *context.T, name string, object interface{}, auth security.Authorizer, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)

	// WithNewDispatchingServer creates a new Server instance to serve a given dispatcher.
	//
	// WithNewDispatchingServer is similar to WithNewServer except it
	// allows users to specify a dispatcher, which provides control over
	// which object and authorizer are used for each method call.  RPCs
	// invoked on the supplied name will be delivered to the supplied
	// Dispatcher's Lookup method which will returns the object and
	// security.Authorizer used to serve the actual RPC call.
	WithNewDispatchingServer(ctx *context.T, name string, disp rpc.Dispatcher, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)
}

Runtime is the interface that concrete Vanadium implementations must implement. It will not be used directly by application builders. They will instead use the package level functions that mirror these factories.

type RuntimeFactory

type RuntimeFactory func(ctx *context.T) (Runtime, *context.T, Shutdown, error)

A RuntimeFactory represents the combination of hardware, operating system, compiler and libraries available to the application. The RuntimeFactory creates a runtime implementation with the required hardware, operating system and library specific dependencies included.

The implementations of the RuntimeFactory are intended to capture all of the dependencies implied by that RuntimeFactory. For example, if a RuntimeFactory requires a particular hardware specific library (say Bluetooth support), then the implementation of the RuntimeFactory should include that dependency in the resulting runtime instance; the package implementing the RuntimeFactory should expose the additional APIs needed to use the functionality.

RuntimeFactories range from the generic to the very specific (e.g. "linux" or "my-sprinkler-controller-v2". Applications should, in general, use as generic a RuntimeFactory as possible.

RuntimeFactories are registered using v23.RegisterRuntimeFactory. Packages that implement RuntimeFactories will typically call RegisterRuntimeFactory in their init functions so importing a RuntimeFactory will be sufficient to register it. Only one RuntimeFactory can be registered in any program, and subsequent registrations will panic. Typically a program's main package will be the only place to import a RuntimeFactory.

This scheme allows applications to use a pre-supplied RuntimeFactory as well as for developers to create their own RuntimeFactories (to represent their hardware and software system).

At a minimum a RuntimeFactory must do the following:

- Initialize a Runtime implementation (providing the flags to it)
- Return a Runtime implementation, initial context, Shutdown func.

See the v.io/x/ref/runtime/factories package for a complete description of the precanned RuntimeFactories and how to use them.

type Shutdown

type Shutdown func()

func Init

func Init() (*context.T, Shutdown)

Init should be called once for each vanadium executable, providing the setup of the vanadium initial context.T and a Shutdown function that can be used to clean up the runtime. We allow calling Init multiple times (useful in tests), but only as long as you call the Shutdown returned previously before calling Init the second time. Init panics if it encounters an error.

func TryInit

func TryInit() (*context.T, Shutdown, error)

TryInit is like Init, except that it returns an error instead of panicking.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier