Documentation
¶
Overview ¶
- ORBIT - Interlink Remote Applications *
- The MIT License (MIT) *
- Copyright (c) 2018 Roland Singer <roland.singer[at]desertbit.com>
- Copyright (c) 2018 Sebastian Borchers <sebastian[at]desertbit.com> *
- Permission is hereby granted, free of charge, to any person obtaining a copy
- of this software and associated documentation files (the "Software"), to deal
- in the Software without restriction, including without limitation the rights
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- copies of the Software, and to permit persons to whom the Software is
- furnished to do so, subject to the following conditions: *
- The above copyright notice and this permission notice shall be included in all
- copies or substantial portions of the Software. *
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- SOFTWARE.
Package signaler makes it possible to send events between connected peers in a network. It uses the orbit control package to send and register these events (https://github.com/desertbit/orbit/control).
The signals can carry a payload.
Registering signals ¶
Each peer can register signals during the initialization, which are then available to the remote peer to listen to. A signal must have a unique identifier.
Listening on signals ¶
The remote peer can then listen on the registered signals by using either the On- functions (getting notified every time the signal is triggered) or the Once- functions (getting notified only once). At each point in time, a remote peer can also stop listening on signals to not receive any notifications after that.
Filtering ¶
It is possible when adding a new signal to set a filter function on a signal. Peers can then set filter data on this signal that gets passed to this filter func. Depending on the return of the filter func, the signal may not be triggered for this peer, if its filter is not fulfilled. This allows peers to filter the signals to their liking and prevents a waste of resources.
Index ¶
- Variables
- type Context
- type Filter
- type FilterFunc
- type Group
- type Listener
- type Signaler
- func (s *Signaler) AddSignal(id string)
- func (s *Signaler) AddSignalFilter(id string, filterFunc FilterFunc)
- func (s *Signaler) AddSignals(ids []string)
- func (s *Signaler) OnSignal(id string) *Listener
- func (s *Signaler) OnSignalFunc(id string, f func(ctx *Context)) *Listener
- func (s *Signaler) OnSignalOpts(id string, channelSize int) *Listener
- func (s *Signaler) OnceSignal(id string) *Listener
- func (s *Signaler) OnceSignalFunc(id string, f func(ctx *Context)) *Listener
- func (s *Signaler) OnceSignalOpts(id string, channelSize int) *Listener
- func (s *Signaler) Ready()
- func (s *Signaler) SetSignalFilter(id string, data interface{}) (err error)
- func (s *Signaler) TriggerSignal(id string, data interface{}) (err error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrSignalNotFound is an error indicating that a signal could not be found. ErrSignalNotFound = errors.New("signal not found") // ErrFilterFuncUndefined is an error indicating that a signal is missing its // filter func. ErrFilterFuncUndefined = errors.New("could not set filter, filter func is missing") )
var ( // ErrNoContextData is an error indicating that no context data is available. ErrNoContextData = errors.New("no context data available to decode") )
Functions ¶
This section is empty.
Types ¶
type Context ¶
type Context struct {
// Data is the raw byte representation of the encoded context data.
Data []byte
// contains filtered or unexported fields
}
The Context type defines a signal context carrying the payload data that has been sent in the trigger request. It offers a convenience wrapper to the data, as it wraps its codec and offers easy access to the decoded data.
type Filter ¶
The Filter type is a function that takes the trigger data and returns whether the data conforms to some predefined conditions, and is allowed to be triggered. This func is returned by the FilterFunc to create a static filter that is fed with dynamic data at runtime.
type FilterFunc ¶
The FilterFunc type takes a request context and returns a new filter func that will be set as the signal's filter.
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
The Group type represents a group of signalers. It is useful for triggering the same signal with some data on all signalers contained in the group. A Group is thread-safe.
func (*Group) Add ¶
Add adds the given signalers to the group. When a signaler is closed, it is automatically removed from the group. There is no need to call Remove() in that case.
func (*Group) Remove ¶
Remove removes the given signalers from this group. If a signaler is not in the group, this method is a no-op for it.
func (*Group) TriggerSignal ¶
TriggerSignal calls each signaler's TriggerSignal() method of this group with the given id and the given data. If a signaler in the group does not contain the signal with the given id, the error is ignored and all other signalers are still triggered.
Signalers can be explicitly excluded from being triggered.
type Listener ¶
type Listener struct {
// C is filled up with the trigger actions from the signaler.
// Use OffChan() to stop your reading routine.
C <-chan *Context
// contains filtered or unexported fields
}
The Listener type represents one party that is interested in being notified, when a specific signal gets triggered. It offers a public channel that contains the context of a trigger, each time it gets triggered.
type Signaler ¶
The Signaler type is the main type to interact with signals on one peer. It contains the underlying control.Control, codecs, loggers, etc. It takes care of storing signals that have been added to it and keeps track of who is listening on which signal.
func (*Signaler) AddSignalFilter ¶
func (s *Signaler) AddSignalFilter(id string, filterFunc FilterFunc)
AddSignalFilter adds a signal with the given id to the signaler. In addition, a filter func is given that is directly set as filter on this signal.
func (*Signaler) AddSignals ¶
AddSignals adds the signals with the given ids to the signaler.
func (*Signaler) OnSignal ¶
OnSignal adds a listener to the signal with the given id. The Listener will output a request context on its channel when the signal has been triggered.
func (*Signaler) OnSignalFunc ¶
OnSignalFunc adds a listener like OnSignal() does, but takes a function that is executed whenever the signal is triggered.
func (*Signaler) OnSignalOpts ¶
OnSignalOpts adds a listener like OnSignal() does, but allows to configure the channel size of the listener. This determines how many events can be buffered in the listener before the triggerSignal handler func will block and further events can not be processed. The size of the channel must be greater than 0 (Unbuffered channels are not allowed).
func (*Signaler) OnceSignal ¶
OnceSignal adds a listener like OnSignal() does, but the listener can only be triggered once and gets removed after the first event.
func (*Signaler) OnceSignalFunc ¶
OnSignalFunc adds a listener like OnceSignal() does, but takes a function that is executed when the signal is triggered.
func (*Signaler) OnceSignalOpts ¶
OnceSignalOpts adds a listener like OnceSignal() does, but allows to configure the channel size of the listener. This determines how many events can be buffered in the listener before the triggerSignal handler func will block and further events can not be processed. The size of the channel must be greater than 0 (Unbuffered channels are not allowed).
func (*Signaler) Ready ¶
func (s *Signaler) Ready()
Ready signalizes that the initialization is done. Signaler can now be triggered. This should be only called once.
func (*Signaler) SetSignalFilter ¶
SetSignalFilter sets the filter data on the signal with the given id. The data will be passed to the filter function and determine, when the signal is triggered. Returns ErrFilterFuncUndefined, if no filter func is defined on the signal. Returns ErrSignalNotFound, if the signal does not exist.
func (*Signaler) TriggerSignal ¶
TriggerSignal triggers the signal with the given id and sends the given data along to the peers. If data is nil, the signal carries no payload. Returns ErrSignalNotFound, if the signal could not be found.
Source Files