1.0.23.69: Add docstrings to SB-BSD-SOCKETS:SOCKET-MAKE-STREAM.

* Contributed by Robert Goldman.

diff --git a/contrib/sb-bsd-sockets/sockets.lisp b/contrib/sb-bsd-sockets/sockets.lisp
index 549b471..e21228f 100644 (file)
--- a/contrib/sb-bsd-sockets/sockets.lisp
+++ b/contrib/sb-bsd-sockets/sockets.lisp
@@ -347,22 +347,45 @@ calls CLOSE on that stream instead"))
                nil))))))
 
 
-(defgeneric socket-make-stream (socket &rest args)
+(defgeneric socket-make-stream (socket &key input output
+                                       element-type external-format
+                                       buffering
+                                       timeout)
   (:documentation "Find or create a STREAM that can be used for IO on
-SOCKET (which must be connected).  ARGS are passed onto
-SB-SYS:MAKE-FD-STREAM."))
-
-(defmethod socket-make-stream ((socket socket) &rest args)
+SOCKET \(which must be connected\).  Specify whether the stream is for
+INPUT, OUTPUT, or both \(it is an error to specify neither\).  ELEMENT-TYPE
+and EXTERNAL-FORMAT are as per OPEN.  TIMEOUT specifies a read timeout
+for the stream."))
+
+(defmethod socket-make-stream ((socket socket)
+                               &key input output
+                               (element-type 'character)
+                               (buffering :full)
+                               (external-format :default)
+                               timeout)
+  "Default method for SOCKET objects.  An ELEMENT-TYPE of :DEFAULT
+will construct a bivalent stream.  Acceptable values for BUFFERING
+are :FULL, :LINE and :NONE.  Streams will have no TIMEOUT
+by default.
+  The stream for SOCKET will be cached, and a second invocation of this
+method will return the same stream.  This may lead to oddities if this
+function is invoked with inconsistent arguments \(e.g., one might request
+an input stream and get an output stream in response\)."
   (let ((stream
          (and (slot-boundp socket 'stream) (slot-value socket 'stream))))
     (unless stream
-      (setf stream (apply #'sb-sys:make-fd-stream
-                          (socket-file-descriptor socket)
-                          :name "a socket"
-                          :dual-channel-p t
-                          args))
+      (setf stream (sb-sys:make-fd-stream
+                    (socket-file-descriptor socket)
+                    :name "a socket"
+                    :dual-channel-p t
+                    :input input
+                    :output output
+                    :element-type element-type
+                    :buffering buffering
+                    :external-format external-format
+                    :timeout timeout)))
       (setf (slot-value socket 'stream) stream)
-      (sb-ext:cancel-finalization socket))
+    (sb-ext:cancel-finalization socket)
     stream))
 
 \f

diff --git a/version.lisp-expr b/version.lisp-expr
index d8008a5..298244c 100644 (file)
--- a/version.lisp-expr
+++ b/version.lisp-expr
@@ -17,4 +17,4 @@
 ;;; checkins which aren't released. (And occasionally for internal
 ;;; versions, especially for internal versions off the main CVS
 ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"1.0.23.68"
+"1.0.23.69"