[usocket-cvs] r267 - public_html

Wed Jun 6 17:42:46 UTC 2007

Author: ehuelsmann
Date: Wed Jun  6 13:42:44 2007
New Revision: 267

Modified:
   public_html/api-docs.shtml
Log:
Some layout improvements. And extra FAQ info.

Modified: public_html/api-docs.shtml
==============================================================================

--- public_html/api-docs.shtml	(original)
+++ public_html/api-docs.shtml	Wed Jun  6 13:42:44 2007
@@ -7,11 +7,27 @@
   <link rel="stylesheet" type="text/css" href="style.css"/>
   <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
   <style type="text/css">
-dt.sym { font-weight: normal; width: 100%; background-color: #8ca }
+dt.sym {
+  font-weight: normal;
+  background-color: #8ca;
+  border-bottom: 1px solid gray;
+  border-left:  1px solid #bbb;
+  padding-left: 1ex;
+}
 .function-name { font-weight: bold }
 .class-name { font-weight: bold }
 .slot-name { font-weight: bold }
 .var-name { font-weight: bold }
+dl.faq dt {
+  margin-top: 1em;
+  font-weight: bold;
+  font-size: larger;
+}
+pre {
+  background-color: #ace;
+  padding: 1ex;
+  border: 1px solid black;
+}
   </style>
 </head>
 <body>
@@ -142,7 +158,7 @@
 
 <h1><a name="faqs">How do I ...</a></h1>
 
-<dl>
+<dl class="faq">
 <dt>... check whether the other end has closed my socket stream?
 </dt>
 <dd>Reading from a stream which has been closed at the remote end
@@ -154,7 +170,11 @@
 <dd>When you want to check <b>one</b> stream for readiness of input,
   call the
   <a href="http://www.lisp.org/HyperSpec/Body/fun_listen.html">listen</a>
-  function on the stream object associated with the socket.
+  function on the stream object associated with the socket.<br />
+  Example:
+<pre>(listen (usocket:socket-stream your-socket))
+ ==> NIL (if no input is available)
+</pre>
 </dd>
 <dt>... wait for input to become available on (at least) one stream (of a set)
 </dt>
@@ -163,7 +183,53 @@
   for all platforms (except SBCL and LispWorks; both Win32) it's already
   available in trunk (svn://common-lisp.net/project/usocket/svn/usocket/trunk).
   <br />
-  If you want to use this code you're most welcome and feedback is appreciated.
+  If you want to use this code you're most welcome and feedback is appreciated.<br />
+  Example to be used with trunk:
+<pre>(usocket:wait-for-input (list socket1 socket2 socket3) :timeout <your optional timeout value>)
+ ==> list-of-sockets-to-read-from</pre>
+</dd>
+<dt>... convert my existing trivial-sockets based application to usocket?
+</dt>
+<dd>There are actually 3 answers to that question.
+  <ol>
+    <li>Rewrite your code to keep a usocket object instead of the stream
+      object returned by trivial-sockets.</li>
+    <li>The quick conversion with the good performance characteristics
+      (use only when you don't want to use the socket object):<br />
+      Replace all your invocations of
+<pre>
+  (trivial-sockets:open-socket-stream ....)
+
+with
+  (usocket:socket-stream (usocket:socket-connect ...))
+</pre>
+
+And replace all invocations of
+<pre>
+  (trivial-sockets:socket-accept ...)
+
+with
+  (usocket:socket-stream (usocket:socket-accept ...))
+</pre>
+
+And replace all invocations of
+<pre>
+  (trivial-sockets:open-server ...)
+
+with
+  (usocket:socket-listen ...)
+</pre></li>
+    <li>And the last option which provides a compatible
+      (but slower, because it uses Gray streams) interface is to use
+      trivial-usocket.<br />
+      The trivial-usocket package provides a 1-1 mapped interface to
+      trivial-sockets, but uses Gray streams; that way, it's later possible
+      to retrieve the socket object from the stream returned and to use that
+      socket for other usocket operations. Use this approach as a migration
+      path where you're not rewriting your application at once, but in
+      small steps.
+      </li>
+    </ol>
 </dd>
 
 </dl>

