zenoh

package module
v0.0.0-...-505b8b1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 29, 2020 License: Apache-2.0, EPL-2.0 Imports: 10 Imported by: 0

README

zenoh banner

Build GoReport Status Documentation Status Gitter License License

Eclipse zenoh Go API

Eclipse zenoh is an extremely efficient and fault-tolerant Named Data Networking (NDN) protocol that is able to scale down to extremely constrainded devices and networks.

The Go API is for pure clients, in other terms does not support peer-to-peer communication, can be easily tested against a zenoh router running in a Docker container (see https://github.com/eclipse-zenoh/zenoh#how-to-test-it).

How to install it

The zenoh-go library relies on the zenoh-c library. Please install it, either installing the libzenohc-dev package, either building zenoh-c by yourself

Supported Go version: 1.14.0 minimum.

Install the zenoh-go library via the usual go getcommand:

$ go get github.com/eclipse-zenoh/zenoh-go

Running the Examples

The simplest way to run some of the example is to get a Docker image of the zenoh network router (see https://github.com/eclipse-zenoh/zenoh#how-to-test-it) and then to run the examples on your machine.

Then, run the zenoh-go examples following the instructions in examples/zenoh/README.md

Documentation

Overview

Package zenoh provides the Zenoh client API in Go.

Index

Constants

View Source 
const PropPassword = "password"

PropPassword is the "password" property key

View Source 
const PropUser = "user"

PropUser is the "user" property key

Variables

This section is empty.

Functions

func RegisterValueDecoder 

func RegisterValueDecoder(encoding Encoding, decoder ValueDecoder) error

RegisterValueDecoder registers a ValueDecoder function with it's Encoding

Types

type Admin 

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

Admin is the zenoh administration class.

func (*Admin) AddBackend 

func (a *Admin) AddBackend(beid string, properties Properties) error

AddBackend adds a backend in the connected Zenoh router (i.e. the one you are directly connected to).

The backend will use the properties for initialization and "beid" as identifier.

func (*Admin) AddBackendAt 

func (a *Admin) AddBackendAt(beid string, properties Properties, zenoh string) error

AddBackendAt adds a backend in the specified Zenoh router, not necessarily the one you are connected to.

The backend will use the properties for initialization and "beid" as identifier.

func (*Admin) AddStorage 

func (a *Admin) AddStorage(stid string, properties Properties) error

AddStorage adds a storage in the connected Zenoh router, using an automatically chosen backend.

The storage will use the properties for initialization and "stid" as identifier.

func (*Admin) AddStorageAt 

func (a *Admin) AddStorageAt(stid string, properties Properties, zenoh string) error

AddStorageAt adds a storage in the specified Zenoh router, using an automatically chosen backend.

The storage will use the properties for initialization and "stid" as identifier.

func (*Admin) AddStorageOnBackend 

func (a *Admin) AddStorageOnBackend(stid string, properties Properties, backend string) error

AddStorageOnBackend adds a storage in the connected Zenoh router, using the specified backend.

func (*Admin) AddStorageOnBackendAt 

func (a *Admin) AddStorageOnBackendAt(stid string, properties Properties, backend string, zenoh string) error

AddStorageOnBackendAt adds a storage in the specified Zenoh router, using the specified backend.

func (*Admin) GetBackend 

func (a *Admin) GetBackend(beid string) (Properties, error)

GetBackend gets a backend's properties from the connected Zenoh router. (i.e. the one you are directly connected to).

func (*Admin) GetBackendAt 

func (a *Admin) GetBackendAt(beid string, zenoh string) (Properties, error)

GetBackendAt gets a backend's properties from the specified Zenoh router, not necessarily the one you are connected to.

func (*Admin) GetBackends 

func (a *Admin) GetBackends() (map[string]Properties, error)

GetBackends gets all the backends from the connected Zenoh router (i.e. the one you are directly connected to).

It returns a map of the backends properties, indexed by the backends identifiers.

func (*Admin) GetBackendsAt 

func (a *Admin) GetBackendsAt(zenoh string) (map[string]Properties, error)

GetBackendsAt gets all the backends from the specified Zenoh router, not necessarily the one you are connected to.

It returns a map of the backends properties, indexed by the backends identifiers.

func (*Admin) GetStorage 

func (a *Admin) GetStorage(stid string) (Properties, error)

GetStorage gets a storage's properties from the connected Zenoh router.

func (*Admin) GetStorageAt 

func (a *Admin) GetStorageAt(stid string, zenoh string) (Properties, error)

GetStorageAt gets a storage's properties from the specified Zenoh router.

func (*Admin) GetStorages 

func (a *Admin) GetStorages() (map[string]Properties, error)

GetStorages gets all the storages from the connected Zenoh router.

It returns a map of the stgorages properties, indexed by the storages identifiers.

func (*Admin) GetStoragesAt 

func (a *Admin) GetStoragesAt(zenoh string) (map[string]Properties, error)

GetStoragesAt gets all the storages from the specified Zenoh router.

It returns a map of the stgorages properties, indexed by the storages identifiers.

func (*Admin) GetStoragesFromBackend 

func (a *Admin) GetStoragesFromBackend(backend string) (map[string]Properties, error)

GetStoragesFromBackend gets all the storages from the specified backend within the connected Zenoh router.

It returns a map of the stgorages properties, indexed by the storages identifiers.

func (*Admin) GetStoragesFromBackendAt 

func (a *Admin) GetStoragesFromBackendAt(backend string, zenoh string) (map[string]Properties, error)

GetStoragesFromBackendAt gets all the storages from the specified backend within the specified Zenoh router.

It returns a map of the stgorages properties, indexed by the storages identifiers.

func (*Admin) RemoveBackend 

func (a *Admin) RemoveBackend(beid string) error

RemoveBackend removes a backend from the connected Zenoh router (i.e. the one you are directly connected to).

func (*Admin) RemoveBackendAt 

func (a *Admin) RemoveBackendAt(beid string, zenoh string) error

RemoveBackendAt removes a backend from the specified Zenoh router, not necessarily the one you are connected to.

func (*Admin) RemoveStorage 

func (a *Admin) RemoveStorage(stid string) error

RemoveStorage removes a storage from the connected Zenoh router.

func (*Admin) RemoveStorageAt 

func (a *Admin) RemoveStorageAt(stid string, zenoh string) error

RemoveStorageAt removes a storage from the specified Zenoh router.

type Change 

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

Change represents the notification of a change for a resource in zenoh.

The Listener function that is registered in Workspace.subscribe(selector, listener) will receive a list of Changes.

func (*Change) Kind 

func (c *Change) Kind() ChangeKind

Kind returns the kind of change

func (*Change) Path 

func (c *Change) Path() *Path

Path returns the path impacted by the change

func (*Change) Timestamp 

func (c *Change) Timestamp() *Timestamp

Timestamp returns the time of change (as registered in Zenoh)

func (*Change) Value 

func (c *Change) Value() Value

Value returns the value that changed

type ChangeKind 

type ChangeKind = uint8

ChangeKind is a kind of change 

const (
	// PUT represents a change made by a put on Zenoh
	PUT ChangeKind = 0x00
	// UPDATE represents a change made by an update on Zenoh
	UPDATE ChangeKind = 0x01
	// REMOVE represents a change made by a remove on Zenoh
	REMOVE ChangeKind = 0x02
)

type Data 

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

Data is a zenoh data returned by a Workspace.get(selector) query.

The Data objects are comparable according to their Timestamp. Note that zenoh makes sure that each published path/value has a unique timestamp accross the system.

func (*Data) Path 

func (e *Data) Path() *Path

Path returns the path of the Data

func (*Data) Timestamp 

func (e *Data) Timestamp() *Timestamp

Timestamp returns the timestamp of the Data

func (*Data) Value 

func (e *Data) Value() Value

Value returns the value of the Data

type Encoding 

type Encoding = uint8

Encoding is a description of the Value format, allowing zenoh to know how to encode/decode the value to/from a bytes buffer. 

const (
	// RAW: The value has a RAW encoding (i.e. it's a bytes buffer).
	RAW Encoding = 0x00

	// STRING: The value is an UTF-8 string.
	STRING Encoding = 0x02

	// PROPERTIES: The value if a list of keys/values, encoded as an UTF-8 string.
	// The keys/values are separated by ';' character, and each key is separated
	// from its associated value (if any) with a '=' character.
	PROPERTIES Encoding = 0x03

	// JSON The value is a JSON structure in an UTF-8 string.
	JSON Encoding = 0x04

	// INT The value is an integer as an UTF-8 string.
	INT Encoding = 0x06

	// FLOAT The value is a float as an UTF-8 string.
	FLOAT Encoding = 0x07
)

Known encodings:

type Eval 

type Eval func(path *Path, props Properties) Value

Eval defines the callback function that has to be registered for evals

type FloatValue 

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

FloatValue is a FLOAT value (i.e. a float64)

func NewFloatValue 

func NewFloatValue(f float64) *FloatValue

NewFloatValue returns a new FloatValue

func (*FloatValue) Encode 

func (v *FloatValue) Encode() []byte

Encode returns the value encoded as a []byte

func (*FloatValue) Encoding 

func (v *FloatValue) Encoding() Encoding

Encoding returns the encoding flag for an FloatValue

func (*FloatValue) ToString 

func (v *FloatValue) ToString() string

ToString returns the value as a string

type IntValue 

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

IntValue is a INT value (i.e. an int64)

func NewIntValue 

func NewIntValue(i int64) *IntValue

NewIntValue returns a new IntValue

func (*IntValue) Encode 

func (v *IntValue) Encode() []byte

Encode returns the value encoded as a []byte

func (*IntValue) Encoding 

func (v *IntValue) Encoding() Encoding

Encoding returns the encoding flag for an IntValue

func (*IntValue) ToString 

func (v *IntValue) ToString() string

ToString returns the value as a string

type Listener 

type Listener func([]Change)

Listener defines the callback function that has to be registered for subscriptions

type Path 

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

Path is a set of strings separated by '/' , as in a filesystem path. A Path cannot contain any '*' character.

Examples of paths: 

"/demo/example/test"
"/com/adlink/building/fr/floor/1/office/2"

A path can be absolute (i.e. starting with a `'/'`) or relative to a Workspace.

func NewPath 

func NewPath(p string) (*Path, error)

NewPath returns a new Path from the string p, if it's a valid path specification. Otherwise, it returns an error.

func (*Path) AddPrefix 

func (p *Path) AddPrefix(prefix *Path) *Path

AddPrefix returns a new Path made from the concatenation of the prefix and this path.

func (*Path) IsRelative 

func (p *Path) IsRelative() bool

IsRelative returns true if the Path is not absolute (i.e. it doesn't start with '/')

func (*Path) Length 

func (p *Path) Length() int

Length returns length of the path string

func (*Path) ToString 

func (p *Path) ToString() string

ToString returns the Path as a string

type Properties 

type Properties map[string]string

Properties is a (string,string) map

type PropertiesValue 

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

PropertiesValue is a PROPERTIES value (i.e. a map[string]string)

func NewPropertiesValue 

func NewPropertiesValue(p Properties) *PropertiesValue

NewPropertiesValue returns a new PropertiesValue

func (*PropertiesValue) Encode 

func (v *PropertiesValue) Encode() []byte

Encode returns the value encoded as a []byte

func (*PropertiesValue) Encoding 

func (v *PropertiesValue) Encoding() Encoding

Encoding returns the encoding flag for a PropertiesValue

func (*PropertiesValue) ToString 

func (v *PropertiesValue) ToString() string

ToString returns the value as a string

type RawValue 

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

RawValue is a RAW value (i.e. a bytes buffer)

func NewRawValue 

func NewRawValue(buf []byte) *RawValue

NewRawValue returns a new RawValue

func (*RawValue) Encode 

func (v *RawValue) Encode() []byte

Encode returns the value encoded as a []byte

func (*RawValue) Encoding 

func (v *RawValue) Encoding() Encoding

Encoding returns the encoding flag for a RawValue

func (*RawValue) ToString 

func (v *RawValue) ToString() string

ToString returns the value as a string

type Selector 

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

Selector is a string which is the conjunction of an path expression identifying a set of keys and some optional parts allowing to refine the set of Paths and associated Values.

Structure of a selector: 

/s1/s2/../sn?x>1&y<2&..&z=4(p1=v1;p2=v2;..;pn=vn)#a;x;y;..;z
|          | |            | |                  |  |        |
|-- expr --| |-- filter --| |--- properties ---|  |fragment|

where:

- expr: is a path expression. I.e. a string similar to a Path but with character '*' allowed. A single '*' matches any set of characters in a path, except '/'. While `"**"` matches any set of characters in a path, including '/'. A path expression can be absolute (i.e. starting with a '/') or relative to a Workspace.

- filter: a list of predicates separated by '&' allowing to perform filtering on the Value associated with the matching keys. Each predicate has the form "`field“operator“value`" where: -- `field` is the name of a field in the value (is applicable and is existing. otherwise the predicate is false). -- `operator` is one of a comparison operators: `<` , `>` , `<=` , `>=` , `=` , `!=`. -- `value` is the the value to compare the field's value with.

- fragment: a list of fields names allowing to return a sub-part of each value. This feature only applies to structured values using a "self-describing" encoding, such as JSON or XML. It allows to select only some fields within the structure. A new structure with only the selected fields will be used in place of the original value.

NOTE: the filters and fragments are not yet supported in current zenoh version.

func NewSelector 

func NewSelector(s string) (*Selector, error)

NewSelector returns a new Selector from the string s, if it's a valid path specification. Otherwise, it returns an error.

func (*Selector) AddPrefix 

func (s *Selector) AddPrefix(prefix *Path) *Selector

AddPrefix returns a new Selector made from the concatenation of the prefix and this path.

func (*Selector) Fragment 

func (s *Selector) Fragment() string

Fragment returns the fragment part of the Selector

func (*Selector) IsRelative 

func (s *Selector) IsRelative() bool

IsRelative returns true if the Path is not absolute (i.e. it doesn't start with '/')

func (*Selector) OptionalPart 

func (s *Selector) OptionalPart() string

OptionalPart returns the optional part of the Selector (i.e. the part starting from the '?' character to the end of string)

func (*Selector) Path 

func (s *Selector) Path() string

Path returns the path part of the Selector

func (*Selector) Predicate 

func (s *Selector) Predicate() string

Predicate returns the predicate part of the Selector

func (*Selector) Properties 

func (s *Selector) Properties() string

Properties returns the properties part of the Selector

func (*Selector) ToString 

func (s *Selector) ToString() string

ToString returns the Selector as a string

type StringValue 

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

StringValue is a STRING value (i.e. just a string)

func NewStringValue 

func NewStringValue(s string) *StringValue

NewStringValue returns a new StringValue

func (*StringValue) Encode 

func (v *StringValue) Encode() []byte

Encode returns the value encoded as a []byte

func (*StringValue) Encoding 

func (v *StringValue) Encoding() Encoding

Encoding returns the encoding flag for a StringValue

func (*StringValue) ToString 

func (v *StringValue) ToString() string

ToString returns the value as a string

type SubscriptionID 

type SubscriptionID = znet.Subscriber

SubscriptionID identifies a Zenoh subscription

type Timestamp 

type Timestamp = zcore.Timestamp

Timestamp is a Zenoh Timestamp

type Value 

type Value interface {
	Encoding() Encoding
	Encode() []byte
	ToString() string
}

Value is the interface of a value that, associated to a Path, can be published into zenoh via Workspace.put(Path, Value), or retrieved via Workspace.get(Selector) or via a subscription (Workspace.subscribe(Selector, Listener)).

type ValueDecoder 

type ValueDecoder func([]byte) (Value, error)

ValueDecoder is a decoder for a Value

type Workspace 

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

Workspace allows to operate on Zenoh.

func (*Workspace) Get 

func (w *Workspace) Get(selector *Selector) []Data

Get a selection of path/value from Zenoh.

func (*Workspace) Put 

func (w *Workspace) Put(path *Path, value Value) error

Put a path/value into Zenoh.

func (*Workspace) PutBytes 

func (w *Workspace) PutBytes(path *Path, value []byte) error

PutBytes a path/[]bytes into Zenoh.

func (*Workspace) PutFloat 

func (w *Workspace) PutFloat(path *Path, value float64) error

PutFloat a path/float64 into Zenoh.

func (*Workspace) PutInt 

func (w *Workspace) PutInt(path *Path, value int64) error

PutInt a path/int64 into Zenoh.

func (*Workspace) PutString 

func (w *Workspace) PutString(path *Path, value string) error

PutString a path/string into Zenoh.

func (*Workspace) RegisterEval 

func (w *Workspace) RegisterEval(path *Path, eval Eval) error

RegisterEval registers an "eval" function under the provided Path.

func (*Workspace) Remove 

func (w *Workspace) Remove(path *Path) error

Remove a path/value from Zenoh.

func (*Workspace) Subscribe 

func (w *Workspace) Subscribe(selector *Selector, listener Listener) (*SubscriptionID, error)

Subscribe subscribes to a selection of path/value from Zenoh.

The listener will be called for each change of a path/value matching the selection.

func (*Workspace) UnregisterEval 

func (w *Workspace) UnregisterEval(path *Path) error

UnregisterEval unregisters a previously registered evaluation function.

The path is the same that has been used for registration.

func (*Workspace) Unsubscribe 

func (w *Workspace) Unsubscribe(subid *SubscriptionID) error

Unsubscribe unregisters a previous subscription

func (*Workspace) Update 

func (w *Workspace) Update(path *Path, value Value) error

Update a path/value into Zenoh.

type ZError 

type ZError = zcore.ZError

ZError reports an error that occurred in zenoh.

type Zenoh 

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

Zenoh is the Zenoh client API

func Login 

func Login(locator *string, properties Properties) (*Zenoh, error)

Login establishes a zenoh session via a provided locator.

Locator is a string representing the network endpoint to which establish the session. If the provided locator is nil, login will perform some dynamic discovery and try to establish the session automatically. When not nil, the locator must have the format: "tcp/<ip>:<port>" (for instance: "tcp/127.0.0.1:7447").

Properties contains the configuration to be used for this session (e.g. "user", "password"...). It can be nil.

func (*Zenoh) Admin 

func (z *Zenoh) Admin() *Admin

Admin returns the admin object that provides helper operations to administer Zenoh.

func (*Zenoh) Logout 

func (z *Zenoh) Logout() error

Logout terminates the Zenoh session.

func (*Zenoh) Workspace 

func (z *Zenoh) Workspace(path *Path) *Workspace

Workspace creates a Workspace using the provided path. All relative Selector or Path used with this Workspace will be relative to this path.

Notice that all subscription listeners and eval callbacks declared in this workspace will be executed by the I/O subroutine. This implies that no long operations or other call to Zenoh shall be performed in those callbacks.

func (*Zenoh) WorkspaceWithExecutor 

func (z *Zenoh) WorkspaceWithExecutor(path *Path) *Workspace

WorkspaceWithExecutor creates a Workspace using the provided path. All relative Selector or Path used with this Workspace will be relative to this path.

Notice that all subscription listeners and eval callbacks declared in this workspace will be executed by their own subroutine. This is useful when listeners and/or callbacks need to perform long operations or need to call other Zenoh operations.

Source Files

View all Source files

Directories

Path Synopsis
examples
zenoh-net/zn_eval
zenoh-net/zn_info
zenoh-net/zn_pub_thr
zenoh-net/zn_pull
zenoh-net/zn_query
zenoh-net/zn_storage
zenoh-net/zn_stream
zenoh-net/zn_sub
zenoh-net/zn_sub_thr
zenoh-net/zn_write
zenoh/z_add_storage
zenoh/z_eval
zenoh/z_get
zenoh/z_put
zenoh/z_put_float
zenoh/z_put_thr
zenoh/z_remove
zenoh/z_sub
zenoh/z_sub_thr
Package net provides the Zenoh-net API in Go.
 Package net provides the Zenoh-net API in Go.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.