Documentation
¶
Overview ¶
Package comms implements a protocol of communication wih the front-ent (notebook), and it's used to implement widgets.
The front-end uses a WebSocket to connect to Jupyter Server, which in turns uses ZeroMQ (a framework for communication) to talk to GoNB, which in turns uses named pipes to talk to the user program (when executing cells).
Widgets developers can simply use this library as is. For GoNB developers there is a more detailed description of what is going on in `gonb/docs/FrontEndCommunication.md`.
Errors on the underlying named pipes used to connect to GoNB can be checked with gonbui.Error().
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConvertTo ¶
func ConvertTo[T protocol.CommValueTypes](from any) (to T, err error)
ConvertTo converts from `any` value to one of the `CommValueTypes`. If the conversion fails, it returns an error.
func ReadValue ¶
func ReadValue[T protocol.CommValueTypes](address string) (value T)
ReadValue from the front-end, using "comms", a channel used to talk to a WebSocket in the browser (notebook). It may lock waiting for a reply if something goes wrong with the channel in between the request, so consider running this in a goroutine and handling gracefully such cases (with a timeout?).
Notice anyone subscribed (Subscribe) to the address will also receive the value read.
This is used to implement widgets, or arbitrary Javascript/Wasm code running in the front-end.
func Send ¶
func Send[T protocol.CommValueTypes](address string, value T)
Send to the front-end, using "comms", a virtual channel used to talk to a WebSocket in the browser (notebook).
This is used to implement widgets, or arbitrary Javascript/Wasm code running in the front-end.
func Start ¶
func Start()
Start makes sure that the `gonb_comm` Javascript module, responsible for communication with GoNB, is installed in the front-end.
This happens automatically if one uses any of the other functions, but if one is trying to use the Javacript API before that, be sure to call this at the start of your program.
This is equivalent of running the special command `%widgets`.
func Unsubscribe ¶
func Unsubscribe(id SubscriptionId)
Unsubscribe from receiving front-end updates, using the SubscriptionId returned by Subscribe.
Types ¶
type AddressChan ¶
type AddressChan[T protocol.CommValueTypes] struct { C chan T // contains filtered or unexported fields }
AddressChan provides a channel to listen to an Address in the communication between the front-end and GoNB.
It can be used to interact with the front-end (the browser) in a notebook.
Use Listen to create an AddressChan, and use `C` to receive the updates.
It's a common output of widgets, to listen to its updates.
func Listen ¶
func Listen[T protocol.CommValueTypes](address string) *AddressChan[T]
Listen returns an unbuffered channel (`*AddressChannel[T]`) that listens to incoming updates from the front-end to the incoming address.
This can be used to directly get updates to widgets that use those addresses.
A few resources are used to subscribe to the address. Use `AddressChan[T].Close()` to release those resources, when done listening.
func (*AddressChan[T]) Close ¶
func (c *AddressChan[T]) Close()
Close closes the channel and unsubscribe from messages on this address, freeing up resources.
AddressChan doesn't use many resources, one may just leak these without consequences if only a few thousand.
func (*AddressChan[T]) IsClosed ¶
func (c *AddressChan[T]) IsClosed() bool
IsClosed checks whether this AddressChannel is closed.
func (*AddressChan[T]) LatestOnly ¶
func (c *AddressChan[T]) LatestOnly() *AddressChan[T]
LatestOnly replaces the underlying channel `AddressChan[T].C` with one with buffer size 1.
This channel drops results if they are not read often enough -- when values are generated faster in the channel than one is reading from the channel. But the reader will always read the latest incoming value -- so always the freshest value.
This is useful, for instance, when one is doing a slow drawing in response to some UI element (like a slider), where one only wishes to redraw the latest value received, where there is one.
To achieve this, when writing new incoming values to the channel, if the channel buffer is full, it consumes it and then writes the new value.
func (*AddressChan[T]) WaitClose ¶
func (c *AddressChan[T]) WaitClose()
WaitClose waits until the AddressChan.Close is called.
func (*AddressChan[T]) WithBuffer ¶
func (c *AddressChan[T]) WithBuffer(n int) *AddressChan[T]
WithBuffer replaces the underlying channel `AddressChan[T].C` with one with buffer size `n`.
This should be called just after the creation of the AddressChan, since anything received in between the creation and this call will be dropped.
It returns itself, to allow cascaded settings.
type SubscriptionId ¶
type SubscriptionId int
SubscriptionId is returned upon a subscription, and is used to unsubscribe. It can be discarded if one is never going to unsubscribe.
func Subscribe ¶
func Subscribe[T protocol.CommValueTypes](address string, callback func(address string, value T)) SubscriptionId
Subscribe to updates on the given address. It returns a SubscriptionId that can be used with Unsubscribe.
Source Files