Jupyter.ZeroMQ

This is a primarily internal module; users of the jupyter package do not need to import or use functions or data types from this module.

This module provides a low-level interface to the Jupyter ZeroMQ sockets, message encoding, and message decoding. The primary interface consists of withKernelSockets and withClientSockets, which create the sets of sockets needed to serve a kernel or run a client, and sendMessage and receiveMessage, which, as the names may imply, send and receive messages (encoding and decoding them along the way) on the sockets.

Opening ZeroMQ Sockets

data KernelSockets z

The collection of ZeroMQ sockets needed to communicate with Jupyter clients on the Jupyter messaging wire protocol. These sockets are to be used by a kernel communicating with a client.

Roles of different sockets are described here.

Constructors

KernelSockets

Fields

kernelHeartbeatSocket :: Socket z Rep

The heartbeat socket, which echoes anything sent to it immediately and is used by frontends solely to confirm that the kernel is still alive.

kernelControlSocket :: Socket z Router

The control socket, optionally used to send ClientRequest messages that deserve immediate response (shutdown requests, etc), rather than long-running requests (execution).

kernelShellSocket :: Socket z Router

The shell socket, used to send the majority of ClientRequest messages (introspection, completion, execution, etc) and their responses.

kernelStdinSocket :: Socket z Router

The stdin socket, used for communication from a kernel to a single frontend; currently only used for retrieving standard input from the user, hence the socket name.

kernelIopubSocket :: Socket z Pub

The iopub socket, used for publishing KernelOutputs to all frontends.

withKernelSockets

Arguments

:: Maybe KernelProfile

Optionally, specify how the ZeroMQ sockets should be opened, including the ports on which they should be opened. If Nothing is provided, ports are chosen automatically, and a KernelProfile is generated with the chosen ports.

-> (forall z. KernelProfile -> KernelSockets z -> ZMQ z a)

Callback to invoke with the socket info and ZeroMQ sockets.

-> IO a

Create and bind all ZeroMQ sockets used for serving a Jupyter kernel. Store info about the created sockets in a KernelProfile, and then run a ZMQ action, providing the used KernelProfile and the sockets themselves in a JupyterSockets record.

data ClientSockets z

The collection of ZeroMQ sockets needed to communicate with Jupyter kernels on the Jupyter messaging wire protocol. These sockets are to be used by a client communicating with a kernel.

Roles of different sockets are described here.

Constructors

ClientSockets

Fields

clientHeartbeatSocket :: Socket z Req

The heartbeat socket, which, for functioning kernels, will echo anything sent to it immediately. Clients can use this socket to check if the kernel is still alive.

clientControlSocket :: Socket z Dealer

The control socket, optionally used to send ClientRequest messages that deserve immediate response (shutdown requests, etc), rather than long-running requests (execution).

clientShellSocket :: Socket z Dealer

The shell socket, used to send the majority of ClientRequest messages (introspection, completion, execution, etc) and their responses.

clientStdinSocket :: Socket z Dealer

The stdin socket, used for communication from a kernel to a single frontend; currently only used for retrieving standard input from the user, hence the socket name.

clientIopubSocket :: Socket z Sub

The iopub socket, used for receiving KernelOutputs from the kernel.

clientWaitForConnections :: IO ()

A function which waits for one connection on each of the sockets, using socket monitoring.

withClientSockets

Arguments

:: Maybe KernelProfile

Optionally, specify how the ZeroMQ sockets should be opened, including the ports on which they should be opened. If Nothing is provided, ports are chosen automatically, and a KernelProfile is generated with the chosen ports.

-> (forall z. KernelProfile -> ClientSockets z -> ZMQ z a)

Callback to invoke with the socket info and ZeroMQ sockets.

-> IO a

Create and bind all ZeroMQ sockets used for using a Jupyter kernel from a client. Store info about the created sockets in a KernelProfile, and then run a ZMQ action, providing the used KernelProfile and the sockets themselves in a JupyterSockets record.

Kernel Profiles

data KernelProfile

A kernel profile, specifying how the kernel communicates.

The kernel profile is usually obtained by a kernel by parsing the connection file passed to it as an argument as indicated by the kernelspec.

The profileTransport, profileIp and five profile Port fields specify the ports which the kernel should bind to. These ports are usually generated fresh for every client or server started.

profileSignatureKey is used to cryptographically sign messages, so that other users on the system can’t send code to run in this kernel. See the wire protocol documentation for the details of how this signature is calculated.

More info on the fields of the connection file and the KernelProfile is available in the respective Jupyter documentation.

Constructors

KernelProfile

Fields

profileIp :: IP

The IP on which to listen.

profileTransport :: Transport

The transport mechanism.

profileStdinPort :: Port

The stdin channel port.

profileControlPort :: Port

The control channel port.

profileHeartbeatPort :: Port

The heartbeat channel port.

profileShellPort :: Port

The shell command port.

profileIopubPort :: Port

The IOPub port.

profileSignatureKey :: ByteString

The HMAC encryption key.

Instances

Eq KernelProfile

Ord KernelProfile

Read KernelProfile

Show KernelProfile

ToJSON KernelProfile

Instance to decode a KernelProfile from connection file contents.

FromJSON KernelProfile

Decode a KernelProfile from a JSON object.

This object is passed to kernels in the connection file.

type Port = Int

A TCP port, encoded as an integer.

type IP = String

An IP address, encoded as a string.

data Transport

The transport mechanism used to communicate with the Jupyter frontend.

Constructors

TCP

Default transport mechanism via TCP.

Instances

Eq Transport

Ord Transport

Read Transport

Show Transport

ToJSON Transport

Encode a transport mechanism as a JSON string.

FromJSON Transport

Decode a transport mechanism from a JSON string.

readProfile :: FilePath -> IO (Maybe KernelProfile)

Read a KernelProfile from a file. This file (the connection file) should contain a JSON-encoded object with all necessary fields, as described in the connection files section of the Jupyter documentation.

If the file contents cannot be parsed, Nothing is returned.

writeProfile :: KernelProfile -> FilePath -> IO ()

Write a KernelProfile to a JSON file, which can be passed as the connection file to a starting kernel.

Sending and Receiving messages

sendMessage

Arguments

:: (IsMessage v, Sender a)

=> ByteString

HMAC key used to sign the message.

-> Socket z a

Socket on which to send the message.

-> MessageHeader

Header for the message.

-> v

Data type representing the message to be send.

-> ZMQ z ()

Send a Jupyter message on a socket, encoding it as described in the wire protocol documentation.

receiveMessage :: (IsMessage v, Receiver a) => Socket z a -> ZMQ z (Either String (MessageHeader, v))

Read a client message from a ZeroMQ socket, as well as the message header that came with it. Block until all data for the message has been received.

If receiving all the data succeeds but parsing fails, return a String error message.

This message is polymorphic in its return type v, and so may be used to parse any message type.

mkRequestHeader

Arguments

:: IsMessage v

=> UUID

Session UUID for this client session

-> Username

Username to use in the header

-> v

Message for which to make header (necessary to get MessageType)

-> IO MessageHeader

New MessageHeader, with fresh randomly generated id

Create a new MessageHeader, which is suitable to be used for a request from a client to a kernel.

The main difference between mkRequestHeader and mkReplyHeader is that a reply header has a parent header, while a request header is not triggered by another message, and so has no parent header. However, since there is no parent header to inherit information from, the session UUID and username must be set explicitly.

mkReplyHeader

Arguments

:: IsMessage v

=> MessageHeader

Header of message being replied to

-> v

Reply message for which to generate header (necessary to get MessageType)

-> IO MessageHeader

New MessageHeader, with fresh randomly generated id

Create a new MessageHeader for a message which is a reply to a previous message.

Unlike mkRequestHeader, mkReplyHeader requires a parent header, and so is used for replies, rather than for initiating a communication.

Miscellaneous utilities

threadKilledHandler :: AsyncException -> IO ()

Handle an AsyncException: if the exception is ThreadKilled, then do nothing, otherwise, rethrow the exception.

This helper utility exists to gracefully shutdown infinite loops in which we listen on ZeroMQ sockets, and exists to stop ThreadKilled exceptions from propagating back to the main thread (which, presumably, is the thread that killed the thread in question).

This is a utility provided for use with listener threads.

messagingError

Arguments

:: MonadIO m

=> String

Module name in which error happened.

-> String

Error message.

-> m a

Throw a MessagingException with a descriptive error message.

Should be used when the messaging protocol is not being properly observed or in other unrecoverable situations.

data MessagingException

Exception to throw when the messaging protocol is not being observed.

See messagingError.

Constructors

MessagingException String

Instances

Eq MessagingException

Ord MessagingException

Show MessagingException

Exception MessagingException

An Exception instance allows MessagingException to be thrown as an exception.