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>