[svn-commits] moy: branch moy/webrtc-11 r409679 - /team/moy/webrtc-11/res/res_http_websocket.c

[SVN commits to the Digium repositories]

Author: moy
Date: Tue Mar  4 17:26:45 2014
New Revision: 409679

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=409679
Log:
Formatting comments to match latest reviewboard nitpick

Modified:
    team/moy/webrtc-11/res/res_http_websocket.c

Modified: team/moy/webrtc-11/res/res_http_websocket.c
URL: http://svnview.digium.com/svn/asterisk/team/moy/webrtc-11/res/res_http_websocket.c?view=diff&rev=409679&r1=409678&r2=409679
==============================================================================
--- team/moy/webrtc-11/res/res_http_websocket.c (original)
+++ team/moy/webrtc-11/res/res_http_websocket.c Tue Mar  4 17:26:45 2014
@@ -299,21 +299,31 @@
 
 /* MAINTENANCE WARNING on ast_websocket_read()!
  *
- * We have to keep in mind during this function that the fact that session->fd seems ready (via poll) does not necessarily mean we have application data ready, because in the case
- * of an SSL socket, there is some encryption data overhead that needs to be read from the TCP socket, so poll() may say there are bytes to be read, but whether is just 1 byte or N bytes
- * we do not know that, and we do not know how many of those bytes (if any) are for application data (for us) and not just for the SSL protocol consumption
- *
- * There used to be a couple of nasty bugs here that were fixed in last refactoring but I want to document them so the constraints are clear and we do not re-introduce them:
- *
- * - This function would incorrectly assume that fread() would necessarily return more than 1 byte of data, just because a websocket frame is always >= 2 bytes, but the thing
- *   is we're dealing with a TCP bitstream here, we could read just one byte and that's normal. The problem before was that if just one byte was read, the function bailed out
- *   and returned an error, effectively dropping the first byte of a websocket frame header!
- *
- * - Another subtle bug was that it would just read up to MAX_WS_HDR_SZ (14 bytes) via fread() then assume that executing poll() would tell you if there is more to read, but since
- * we're dealing with a buffered stream (session->f is a FILE*), poll would say there is nothing else to read (in the real tcp socket session->fd) and we would get stuck here
- * without processing the rest of the data in session->f internal buffers until another packet came on the network to unblock us!
- *
- * Note during the header parsing stage we try to read in small chunks just what we need, this is buffered data anyways, no expensive syscall required most of the time ...
+ * We have to keep in mind during this function that the fact that session->fd seems ready
+ * (via poll) does not necessarily mean we have application data ready, because in the case
+ * of an SSL socket, there is some encryption data overhead that needs to be read from the
+ * TCP socket, so poll() may say there are bytes to be read, but whether it is just 1 byte
+ * or N bytes we do not know that, and we do not know how many of those bytes (if any) are
+ * for application data (for us) and not just for the SSL protocol consumption
+ *
+ * There used to be a couple of nasty bugs here that were fixed in last refactoring but I
+ * want to document them so the constraints are clear and we do not re-introduce them:
+ *
+ * - This function would incorrectly assume that fread() would necessarily return more than
+ *   1 byte of data, just because a websocket frame is always >= 2 bytes, but the thing
+ *   is we're dealing with a TCP bitstream here, we could read just one byte and that's normal.
+ *   The problem before was that if just one byte was read, the function bailed out and returned
+ *   an error, effectively dropping the first byte of a websocket frame header!
+ *
+ * - Another subtle bug was that it would just read up to MAX_WS_HDR_SZ (14 bytes) via fread()
+ *   then assume that executing poll() would tell you if there is more to read, but since
+ *   we're dealing with a buffered stream (session->f is a FILE*), poll would say there is
+ *   nothing else to read (in the real tcp socket session->fd) and we would get stuck here
+ *   without processing the rest of the data in session->f internal buffers until another packet
+ *   came on the network to unblock us!
+ *
+ * Note during the header parsing stage we try to read in small chunks just what we need, this
+ * is buffered data anyways, no expensive syscall required most of the time ...
  */
 static inline int ws_safe_read(struct ast_websocket *session, char *buf, int len, enum ast_websocket_opcode *opcode)
 {