stv0g/libwebsockets
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

docs: explain lws_write handling of truncated sends better

Browse source
This commit is contained in:
Andy Green 2016-10-08 18:08:03 +08:00
parent 4be9a5234d
commit abe0c5e57e
4 changed files with 71 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doc/html/group__sending-data.html
View file

@ -206,10 +206,15 @@ Functions</h2></td></tr>
allows maximum efficiency of sending data and protocol in a single
packet while not burdening the user code with any protocol knowledge.
Return may be -1 for a fatal error needing connection close, or a
positive number reflecting the amount of bytes actually sent. This
can be less than the requested number of bytes due to OS memory
pressure at any given time.</pre>
Return may be -1 for a fatal error needing connection close, or the
number of bytes sent.
</pre><h1>Truncated Writes </h1>
<p>The OS may not accept everything you asked to write on the connection.</p>
<p>Posix defines POLLOUT indication from poll() to show that the connection will accept more write data, but it doesn't specifiy how much. It may just accept one byte of whatever you wanted to send.</p>
<p>LWS will buffer the remainder automatically, and send it out autonomously.</p>
<p>During that time, WRITABLE callbacks will be suppressed.</p>
<p>This is to handle corner cases where unexpectedly the OS refuses what we usually expect it to accept. You should try to send in chunks that are almost always accepted in order to avoid the inefficiency of the buffering. </p>
</div>
</div>
</div><!-- contents -->

18
doc/html/group__smtp.html
View file

@ -157,15 +157,15 @@ Functions</h2></td></tr>
<p>sent the session quit </p>
</td></tr>
</table>
<div class="fragment"><div class="line"><a name="l04106"></a><span class="lineno"> 4106</span>&#160; {</div><div class="line"><a name="l04107"></a><span class="lineno"> 4107</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a29e5b0ecf75375b5a643faa3d6222b7c">LGSSMTP_IDLE</a>, </div><div class="line"><a name="l04108"></a><span class="lineno"> 4108</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab89442b7a3ca2b94c3cdcf33756eb933">LGSSMTP_CONNECTING</a>, </div><div class="line"><a name="l04109"></a><span class="lineno"> 4109</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab61778f70ecac007b334bb14942eb41d">LGSSMTP_CONNECTED</a>, </div><div class="line"><a name="l04110"></a><span class="lineno"> 4110</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a1dfec948a864205cec875f63cbe0d4ad">LGSSMTP_SENT_HELO</a>, </div><div class="line"><a name="l04111"></a><span class="lineno"> 4111</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a929bb4623ff3f585108aba2a1b047fab">LGSSMTP_SENT_FROM</a>, </div><div class="line"><a name="l04112"></a><span class="lineno"> 4112</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0aae20a0cb95b97a70f6b45d0ed2d5be83">LGSSMTP_SENT_TO</a>, </div><div class="line"><a name="l04113"></a><span class="lineno"> 4113</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a85e3c452950c09a79086bff4b9be5c14">LGSSMTP_SENT_DATA</a>, </div><div class="line"><a name="l04114"></a><span class="lineno"> 4114</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a38fba41f28d754e38079b31418a86a69">LGSSMTP_SENT_BODY</a>, </div><div class="line"><a name="l04115"></a><span class="lineno"> 4115</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a2c2ed16ffc572326e3040684084b21d5">LGSSMTP_SENT_QUIT</a>, </div><div class="line"><a name="l04116"></a><span class="lineno"> 4116</span>&#160;};</div><div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0ab61778f70ecac007b334bb14942eb41d"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab61778f70ecac007b334bb14942eb41d">LGSSMTP_CONNECTED</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4109</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a38fba41f28d754e38079b31418a86a69"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a38fba41f28d754e38079b31418a86a69">LGSSMTP_SENT_BODY</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4114</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a29e5b0ecf75375b5a643faa3d6222b7c"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a29e5b0ecf75375b5a643faa3d6222b7c">LGSSMTP_IDLE</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4107</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0ab89442b7a3ca2b94c3cdcf33756eb933"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab89442b7a3ca2b94c3cdcf33756eb933">LGSSMTP_CONNECTING</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4108</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0aae20a0cb95b97a70f6b45d0ed2d5be83"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0aae20a0cb95b97a70f6b45d0ed2d5be83">LGSSMTP_SENT_TO</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4112</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a929bb4623ff3f585108aba2a1b047fab"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a929bb4623ff3f585108aba2a1b047fab">LGSSMTP_SENT_FROM</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4111</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a2c2ed16ffc572326e3040684084b21d5"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a2c2ed16ffc572326e3040684084b21d5">LGSSMTP_SENT_QUIT</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4115</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a1dfec948a864205cec875f63cbe0d4ad"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a1dfec948a864205cec875f63cbe0d4ad">LGSSMTP_SENT_HELO</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4110</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a85e3c452950c09a79086bff4b9be5c14"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a85e3c452950c09a79086bff4b9be5c14">LGSSMTP_SENT_DATA</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4113</div></div>
<div class="fragment"><div class="line"><a name="l04120"></a><span class="lineno"> 4120</span>&#160; {</div><div class="line"><a name="l04121"></a><span class="lineno"> 4121</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a29e5b0ecf75375b5a643faa3d6222b7c">LGSSMTP_IDLE</a>, </div><div class="line"><a name="l04122"></a><span class="lineno"> 4122</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab89442b7a3ca2b94c3cdcf33756eb933">LGSSMTP_CONNECTING</a>, </div><div class="line"><a name="l04123"></a><span class="lineno"> 4123</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab61778f70ecac007b334bb14942eb41d">LGSSMTP_CONNECTED</a>, </div><div class="line"><a name="l04124"></a><span class="lineno"> 4124</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a1dfec948a864205cec875f63cbe0d4ad">LGSSMTP_SENT_HELO</a>, </div><div class="line"><a name="l04125"></a><span class="lineno"> 4125</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a929bb4623ff3f585108aba2a1b047fab">LGSSMTP_SENT_FROM</a>, </div><div class="line"><a name="l04126"></a><span class="lineno"> 4126</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0aae20a0cb95b97a70f6b45d0ed2d5be83">LGSSMTP_SENT_TO</a>, </div><div class="line"><a name="l04127"></a><span class="lineno"> 4127</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a85e3c452950c09a79086bff4b9be5c14">LGSSMTP_SENT_DATA</a>, </div><div class="line"><a name="l04128"></a><span class="lineno"> 4128</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a38fba41f28d754e38079b31418a86a69">LGSSMTP_SENT_BODY</a>, </div><div class="line"><a name="l04129"></a><span class="lineno"> 4129</span>&#160; <a class="code" href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a2c2ed16ffc572326e3040684084b21d5">LGSSMTP_SENT_QUIT</a>, </div><div class="line"><a name="l04130"></a><span class="lineno"> 4130</span>&#160;};</div><div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0ab61778f70ecac007b334bb14942eb41d"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab61778f70ecac007b334bb14942eb41d">LGSSMTP_CONNECTED</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4123</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a38fba41f28d754e38079b31418a86a69"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a38fba41f28d754e38079b31418a86a69">LGSSMTP_SENT_BODY</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4128</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a29e5b0ecf75375b5a643faa3d6222b7c"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a29e5b0ecf75375b5a643faa3d6222b7c">LGSSMTP_IDLE</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4121</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0ab89442b7a3ca2b94c3cdcf33756eb933"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0ab89442b7a3ca2b94c3cdcf33756eb933">LGSSMTP_CONNECTING</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4122</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0aae20a0cb95b97a70f6b45d0ed2d5be83"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0aae20a0cb95b97a70f6b45d0ed2d5be83">LGSSMTP_SENT_TO</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4126</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a929bb4623ff3f585108aba2a1b047fab"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a929bb4623ff3f585108aba2a1b047fab">LGSSMTP_SENT_FROM</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4125</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a2c2ed16ffc572326e3040684084b21d5"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a2c2ed16ffc572326e3040684084b21d5">LGSSMTP_SENT_QUIT</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4129</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a1dfec948a864205cec875f63cbe0d4ad"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a1dfec948a864205cec875f63cbe0d4ad">LGSSMTP_SENT_HELO</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4124</div></div>
<div class="ttc" id="group__smtp_html_gga116be79bf44f9dc2a97f46e051fe4dc0a85e3c452950c09a79086bff4b9be5c14"><div class="ttname"><a href="group__smtp.html#gga116be79bf44f9dc2a97f46e051fe4dc0a85e3c452950c09a79086bff4b9be5c14">LGSSMTP_SENT_DATA</a></div><div class="ttdef"><b>Definition:</b> libwebsockets.h:4127</div></div>
</div><!-- fragment -->
</div>
</div>

68
doc/html/libwebsockets_8h_source.html
View file

File diff suppressed because one or more lines are too long

24
lib/libwebsockets.h
View file

@ -3272,10 +3272,25 @@ enum lws_write_protocol {
* allows maximum efficiency of sending data and protocol in a single
* packet while not burdening the user code with any protocol knowledge.
*
* Return may be -1 for a fatal error needing connection close, or a
* positive number reflecting the amount of bytes actually sent. This
* can be less than the requested number of bytes due to OS memory
* pressure at any given time.
* Return may be -1 for a fatal error needing connection close, or the
* number of bytes sent.
*
* Truncated Writes
* ================
*
* The OS may not accept everything you asked to write on the connection.
*
* Posix defines POLLOUT indication from poll() to show that the connection
* will accept more write data, but it doesn't specifiy how much. It may just
* accept one byte of whatever you wanted to send.
*
* LWS will buffer the remainder automatically, and send it out autonomously.
*
* During that time, WRITABLE callbacks will be suppressed.
*
* This is to handle corner cases where unexpectedly the OS refuses what we
* usually expect it to accept. You should try to send in chunks that are
* almost always accepted in order to avoid the inefficiency of the buffering.
*/
LWS_VISIBLE LWS_EXTERN int
lws_write(struct lws *wsi, unsigned char *buf, size_t len,
@ -3284,7 +3299,6 @@ lws_write(struct lws *wsi, unsigned char *buf, size_t len,
/* helper for case where buffer may be const */
#define lws_write_http(wsi, buf, len) \
lws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
///@}
/** \defgroup callback-when-writeable Callback when writeable