Documentation
¶
Overview ¶
Package comms implement the back-end (kernel) protocol over "Custom Messages" used to communicate with the front-end.
This is the counter-part to the `websocket` package, which implements (in javascript) the front-end side.
See documentation in `gonb/docs/FrontEndCommunication.md` with a diagram and description of what is going on.
Index ¶
- Constants
- type State
- func (s *State) Close(msg kernel.Message) error
- func (s *State) HandleMsg(msg kernel.Message) (err error)
- func (s *State) HandleOpen(msg kernel.Message) (err error)
- func (s *State) InstallWebSocket(msg kernel.Message) error
- func (s *State) ProgramFinished()
- func (s *State) ProgramReadValueRequest(address string)
- func (s *State) ProgramSendValueRequest(address string, value any)
- func (s *State) ProgramStart(exec *jpyexec.Executor)
- func (s *State) ProgramSubscribeRequest(address string)
- func (s *State) ProgramUnsubscribeRequest(address string)
- func (s *State) Send(msg kernel.Message, address string, value any) error
- func (s *State) SendHeartbeatAndWait(msg kernel.Message, timeout time.Duration) (heartbeat bool, err error)
Constants ¶
const ( // CommOpenAckAddress is messaged in acknowledgement to a "comm_open" message. CommOpenAckAddress = "#comm_open_ack" // HeartbeatPingAddress is a protocol private message address used as heartbeat request. HeartbeatPingAddress = "#heartbeat/ping" // HeartbeatPongAddress is a protocol private message address used as heartbeat reply. HeartbeatPongAddress = "#heartbeat/pong" )
const ( HeartbeatTimeout = 500 * time.Millisecond HeartbeatRequestThreshold = 1 * time.Second WaitForConnectionTimeout = 3 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type State ¶
type State struct {
// IsWebSocketInstalled indicates if the Javascript that runs a WebSocket that connects to JupyterServer
// (and through that to GoNB) is installed in the front-end.
// This is required for widgets to work: that's how they exchange update information.
// Notice that having it installed doesn't mean yet the connection was established back -- that's what happens
// usually, but it may take some cycles (or fail for any reason).
IsWebSocketInstalled bool
// TransientDisplayId is where javascript code was installed as a transient "display data".
// It is randomly created when the websocket is installed.
// The "transient" cell itself can be cleared after connection is established, to make sure the javascript
// code is not saved.
TransientDisplayId string
// Opened indicates whether "comm_open" message has already been received.
Opened bool
// CommId created when the channel is opened from the front-end.
CommId string
// LastMsgTime is used to condition the need of a heartbeat, to access if the connection is still alive.
LastMsgTime time.Time
// HeartbeatPongLatch is triggered when we receive a heartbeat reply ("pong"), or when it times out.
// A true value means it got the heartbeat, false means it didn't.
// It is recreated everytime a HeartbeatPing is sent.
HeartbeatPongLatch *common.LatchWithValue[bool]
// AddressSubscriptions by the program being executed. Needs to be reset at every program
// execution.
AddressSubscriptions common.Set[string]
// ProgramExecutor is a reference to the executor of the user's program (current cell).
// It is used to dispatch comms coming from the front-end to the program.
// This is set at the start of every cell execution, and reset to nil when the execution finishes.
ProgramExecutor *jpyexec.Executor
// ProgramExecMsg is the kernel.Message used to start the program.
// This is set at the start of every cell execution, and reset to nil when the execution finishes.
ProgramExecMsg kernel.Message
// LogWebsocket controls whether to turn verbose logging (on the Javascript console) of the
// WebSocket Javascript library, when it is installed.
LogWebSocket bool
// contains filtered or unexported fields
}
State for comms protocol. There is a singleton for the kernel, owned by goexec.State.
func (*State) Close ¶
Close connection with front-end. If `msg != nil`, It sends a "comm_close" message.
func (*State) HandleMsg ¶
HandleMsg is called by the dispatcher whenever a new `comm_msg` arrives from the front-end. It filters out messages with the wrong `comm_id`, handles protocol messages (heartbeat) and routes other messages.
func (*State) HandleOpen ¶
HandleOpen message, with `msg_type` set to "comm_open".
If message is incomplete, or apparently not addressed to us, it returns nil (no error) but also doesn't set communications as opened.
func (*State) InstallWebSocket ¶
InstallWebSocket in the front-end, if not already installed. In the browser this is materialized as a global `gonb_comm` object, that handles communication.
If it is supposedly installed, but there has been no communication > `HeartbeatRequestThreshold` (~ 1 second), it probes with a heartbeat "ping" to check.
To install it sends a javascript is output as a transient output, so it's not saved.
If it has already been installed, this does nothing.
func (*State) ProgramFinished ¶
func (s *State) ProgramFinished()
ProgramFinished is called when the program (cell execution) finishes.
func (*State) ProgramReadValueRequest ¶
ProgramReadValueRequest handler, it implements jpyexec.CommsHandler. It sends a message with a request to read the value from the address to the front-end.
This only works if there is a `SyncedVariable` or something similar listening to the address on the front-end.
It also tries to install the WebSocket, if not yet installed.
func (*State) ProgramSendValueRequest ¶
ProgramSendValueRequest handler, it implements jpyexec.CommsHandler. It sends a value to the front-end.
It also tries to install the WebSocket, if not yet installed.
func (*State) ProgramStart ¶
ProgramStart is called each time a program is being executed (the contents of a cell), which is configured to use named pipes (for front-end communication/widgets).
func (*State) ProgramSubscribeRequest ¶
ProgramSubscribeRequest handler, it implements jpyexec.CommsHandler. It subscribes the program to receive updates on the given address.
It also tries to install the WebSocket, if not yet installed.
func (*State) ProgramUnsubscribeRequest ¶
ProgramUnsubscribeRequest handler, it implements jpyexec.CommsHandler. It unsubscribes the program to receive updates on the given address.
It also tries to install the WebSocket, if not yet installed.
func (*State) Send ¶
Send value to the given address in the front-end. This, along with subscribe, is the basic communication operation with the front-end. The value will be converted to JSON before being sent.
func (*State) SendHeartbeatAndWait ¶
func (s *State) SendHeartbeatAndWait(msg kernel.Message, timeout time.Duration) (heartbeat bool, err error)
SendHeartbeatAndWait sends a heartbeat request (ping) and waits for a reply within the given timeout. Returns true if a heartbeat was replied (pong) back, or false if it timed out. It returns an error if it failed to sendData the heartbeat message.
Source Files