- * which all sends are buffered and receives are ignored. This is
- * so that (for example) a new port-forwarding can sit in limbo
- * until its associated SSH channel is ready, and then pending data
- * can be sent on.
+ * which all READABLE notifications are ignored, so that data is
+ * not accepted from the peer until the socket is unfrozen. This
+ * exists for two purposes:
+ *
+ * - Port forwarding: when a local listening port receives a
+ * connection, we do not want to receive data from the new
+ * socket until we have somewhere to send it. Hence, we freeze
+ * the socket until its associated SSH channel is ready; then we
+ * unfreeze it and pending data is delivered.
+ *
+ * - Socket buffering: if an SSH channel (or the whole connection)
+ * backs up or presents a zero window, we must freeze the
+ * associated local socket in order to avoid unbounded buffer
+ * growth.
+ */
+#define sk_set_frozen(s, is_frozen) (((*s)->set_frozen) (s, is_frozen))
+
+/*
+ * Call this after an operation that might have tried to send on a
+ * socket, to clean up any pending network errors.