From be67f63f4e11e53690bf1431a236f86b484c9bf0 Mon Sep 17 00:00:00 2001
From: Diego Nehab <diego.nehab@gmail.com>
Date: Tue, 6 Oct 2015 11:33:50 +0800
Subject: Changed buffer-per-socket to buffer-per-operation.

This is a difficult tradeoff to measure. I think large
datagrams won't be used very frequently. So it is better to
not lock a large buffer to each socket object and instead
allocate and deallocate for each operation receiving a
datagram larger than UDP_DATAGRAMSIZE.
---
 doc/reference.html |  2 ++
 doc/socket.html    | 25 ++++++++++++++++++++++++-
 doc/udp.html       | 33 +++++++--------------------------
 3 files changed, 33 insertions(+), 27 deletions(-)

(limited to 'doc')

diff --git a/doc/reference.html b/doc/reference.html
index 6067ba6..878e7d2 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -147,6 +147,7 @@ Support, Manual">
 <a href="socket.html#connect">connect</a>,
 <a href="socket.html#connect">connect4</a>,
 <a href="socket.html#connect">connect6</a>,
+<a href="socket.html#datagramsize">_DATAGRAMSIZE</a>,
 <a href="socket.html#debug">_DEBUG</a>,
 <a href="dns.html#dns">dns</a>,
 <a href="socket.html#gettime">gettime</a>,
@@ -158,6 +159,7 @@ Support, Manual">
 <a href="socket.html#skip">skip</a>,
 <a href="socket.html#sleep">sleep</a>,
 <a href="socket.html#setsize">_SETSIZE</a>,
+<a href="socket.html#socketinvalid">_SOCKETINVALID</a>,
 <a href="socket.html#source">source</a>,
 <a href="tcp.html#socket.tcp">tcp</a>,
 <a href="tcp.html#socket.tcp4">tcp4</a>,
diff --git a/doc/socket.html b/doc/socket.html
index e6a9bf8..8a81414 100644
--- a/doc/socket.html
+++ b/doc/socket.html
@@ -90,7 +90,7 @@ of connect are defined as simple helper functions that restrict the
 
 <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id=debug> 
+<p class=name id=debug>
 socket.<b>_DEBUG</b>
 </p>
 
@@ -99,6 +99,19 @@ This constant is set to <tt><b>true</b></tt> if the library was compiled
 with debug support.
 </p>
 
+<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=debug>
+socket.<b>_DATAGRAMSIZE</b>
+</p>
+
+<p class=description>
+Default datagram size used by calls to
+<a href="udp.html#receive"<tt>receive</tt></a> and
+<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>.
+(Unless changed in compile time, the value is 8192.)
+</p>
+
 <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=gettime> 
@@ -393,6 +406,16 @@ The maximum number of sockets that the <a
 href=#select><tt>select</tt></a> function can handle. 
 </p>
 
+<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=socketinvalid>
+socket.<b>_SOCKETINVALID</b>
+</p>
+
+<p class=description>
+The OS value for an invalid socket.
+</p>
+
 <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=try> 
diff --git a/doc/udp.html b/doc/udp.html
index 22d7c72..9437c51 100644
--- a/doc/udp.html
+++ b/doc/udp.html
@@ -42,7 +42,7 @@
 <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class="name" id="socket.udp">
-socket.<b>udp(</b>[buffersize]<b>)</b>
+socket.<b>udp()</b>
 </p>
 
 <p class="description">
@@ -62,13 +62,6 @@ The <a href="#setpeername"><tt>setpeername</tt></a>
 is used to connect the object.
 </p>
 
-<p class="parameters">
-The optional <tt>buffersize</tt> parameter
-specifies the size of the largest datagram that will
-ever be received by the UDP object. The default value is
-8192.
-</p>
-
 <p class="return">
 In case of success, a new unconnected UDP object
 returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
@@ -92,7 +85,7 @@ href=#setoption><tt>setoption</tt></a> will fail.
 <!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class="name" id="socket.udp">
-socket.<b>udp4(</b>[buffersize]<b>)</b>
+socket.<b>udp4()</b>
 </p>
 
 <p class="description">
@@ -112,13 +105,6 @@ The <a href="#setpeername"><tt>setpeername</tt></a>
 is used to connect the object.
 </p>
 
-<p class="parameters">
-The optional <tt>buffersize</tt> parameter
-specifies the size of the largest datagram that will
-ever be received by the UDP object. The default value is
-8192.
-</p>
-
 <p class="return">
 In case of success, a new unconnected UDP object
 returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
@@ -128,7 +114,7 @@ an error message.
 <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class="name" id="socket.udp6">
-socket.<b>udp6(</b>[buffersize]<b>)</b>
+socket.<b>udp6()</b>
 </p>
 
 <p class="description">
@@ -148,13 +134,6 @@ The <a href="#setpeername"><tt>setpeername</tt></a>
 is used to connect the object.
 </p>
 
-<p class="parameters">
-The optional <tt>buffersize</tt> parameter
-specifies the size of the largest datagram that will
-ever be received by the UDP object. The default value is
-8192.
-</p>
-
 <p class="return">
 In case of success, a new unconnected UDP object
 returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
@@ -261,8 +240,10 @@ the excess bytes are discarded. If there are less then
 <tt>size</tt> bytes available in the current datagram, the
 available bytes are returned.
 If <tt>size</tt> is omitted, the
-<tt>buffersize</tt> argument at creation time is used
-(which defaults to 8192 bytes).
+compile-time constant <a
+href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used
+(it defaults to 8192 bytes). Larger sizes will cause a
+temporary buffer to be allocated for the operation.
 </p>
 
 <p class="return">
-- 
cgit v1.2.3-55-g6feb