From 276c02cfce35c780c72edbe6b453486571ff123b Mon Sep 17 00:00:00 2001 From: Nathaniel Nicandro Date: Mon, 17 Sep 2018 19:04:55 -0500 Subject: [PATCH] Add more documentation --- jupyter-channels.el | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/jupyter-channels.el b/jupyter-channels.el index a8f5c75..b00d6c8 100644 --- a/jupyter-channels.el +++ b/jupyter-channels.el @@ -39,7 +39,7 @@ :type keyword :initarg :type :documentation "The type of this channel. Should be one of - the keys in `jupyter-channel-socket-types'.") +the keys in `jupyter-channel-socket-types'.") (session :type jupyter-session :initarg :session @@ -63,7 +63,16 @@ send/receive messages.") :type (or null process) :initform nil :documentation "The process responsible for sending and -receiving messages on this channel.") +receiving messages on this channel. + +This subprocess is responsible for receiving message +s-expressions sent by the `jupyter-send' method for a +`jupyter-async-channel', encoding the message, and sending the +encoded message to the kernel. + +The parent Emacs process is then responsible for calling +`jupyter-queue-message' when a message is received from the +subprocess.") (recv-queue :type ring :initform (make-ring 10)) @@ -137,6 +146,22 @@ wait until TIMEOUT for a message." msg)))) (cl-defmethod jupyter-send ((channel jupyter-async-channel) type message &optional msg-id) + "Send an asynchronous MESSAGE on CHANNEL. +MESSAGE is sent to the subprocess in CHANNEL's ioloop slot which +is expected to send the message to the kernel. The list sent to +the subprocess has the following form + + (send CHANNEL-TYPE TYPE MESSAGE MSG-ID) + +where CHANNEL-TYPE is either `:iopub', `:shell', `:hb', +`:control', TYPE is the message type (one of the keys in +`jupyter-message-types'), MESSAGE is the message plist to send, +and MSG-ID is the unique message ID to associate with the message +with nil meaning to generate a new ID. + +When a message is received from the kernel, the subprocess is +responsible for placing the message in CHANNEL's message queue +using `jupyter-queue-message'." (zmq-subprocess-send (oref channel ioloop) (list 'send (oref channel type) type message msg-id)))