feature: implemented the new tcpsok:setoption() function for setting options for the TCP socket.

Author: poorsea

README.markdown

@@ -7789,14 +7789,104 @@ This feature was first introduced in the `v0.10.7` release.
 tcpsock:setoption
 -----------------
 
-**syntax:** *tcpsock:setoption(option, value?)*
+**syntax:** *ok, err = tcpsock:setoption(option, value?)*
 
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua**
 
-This function is added for [LuaSocket](http://w3.impa.br/~diego/software/luasocket/tcp.html) API compatibility and does nothing for now. Its functionality will be implemented in future.
+This function is added for [LuaSocket](http://w3.impa.br/~diego/software/luasocket/tcp.html) API compatibility and does nothing for now. Its functionality is implemented `v0.10.18`.
 
 This feature was first introduced in the `v0.5.0rc1` release.
 
+In case of success, it returns `true`. Otherwise, it returns nil and a string describing the error.
+
+The `option` is a string with the option name, and the value depends on the option being set:
+
+* `keepalive`
+
+	Setting this option to true enables sending of keep-alive messages on
+	connection-oriented sockets. Make sure the `connect` function
+	had been called before, for example,
+
+    ```lua
+
+    local ok, err = tcpsock:setoption("keepalive", true)
+    if not ok then
+        ngx.say("setoption keepalive failed: ", err)
+    end
+    ```
+* `reuseaddr`
+
+	Enabling this option indicates that the rules used in validating addresses
+	supplied in a call to bind should allow reuse of local addresses. Make sure
+	the `connect` function had been called before, for example,
+
+    ```lua
+
+    local ok, err = tcpsock:setoption("reuseaddr", 0)
+    if not ok then
+        ngx.say("setoption reuseaddr failed: ", err)
+    end
+    ```
+* `tcp-nodelay`
+
+	Setting this option to true disables the Nagle's algorithm for the connection.
+	Make sure the `connect` function had been called before, for example,
+
+    ```lua
+
+    local ok, err = tcpsock:setoption("tcp-nodelay", true)
+    if not ok then
+        ngx.say("setoption tcp-nodelay failed: ", err)
+    end
+    ```
+* `sndbuf`
+
+	Sets the maximum socket send buffer in bytes. The kernel doubles this value
+	(to allow space for bookkeeping overhead) when it is set using setsockopt().
+	Make sure the `connect` function had been called before, for example,
+
+    ```lua
+
+    local ok, err = tcpsock:setoption("sndbuf", 1024 * 10)
+    if not ok then
+        ngx.say("setoption sndbuf failed: ", err)
+    end
+    ```
+* `rcvbuf`
+
+	Sets the maximum socket receive buffer in bytes. The kernel doubles this value
+	(to allow space for bookkeeping overhead) when it is set using setsockopt. Make
+	sure the `connect` function had been called before, for example,
+
+    ```lua
+
+    local ok, err = tcpsock:setoption("rcvbuf", 1024 * 10)
+    if not ok then
+        ngx.say("setoption rcvbuf failed: ", err)
+    end
+    ```
+
+NOTE: Once the option is set, it will become effective until the connection is closed. If you know the connection is from the connection pool and all the in-pool connections already have called the setoption() method with the desired socket option state, then you can just skip calling setoption() again to avoid the overhead of repeated calls, for example,
+
+```lua
+
+ local count, err = tcpsock:getreusedtimes()
+ if not count then
+     ngx.say("getreusedtimes failed: ", err)
+     return
+ end
+
+ if count == 0 then
+     local ok, err = tcpsock:setoption("rcvbuf", 1024 * 10)
+     if not ok then
+         ngx.say("setoption rcvbuf failed: ", err)
+         return
+     end
+ end
+```
+
+These options described above are supported in `v0.10.18`, and more options will be implemented in future.
+
 [Back to TOC](#nginx-api-for-lua)
 
 tcpsock:setkeepalive

doc/HttpLuaModule.wiki

@@ -6626,14 +6626,98 @@ This feature was first introduced in the <code>v0.10.7</code> release.
 
 == tcpsock:setoption ==
 
-'''syntax:''' ''tcpsock:setoption(option, value?)''
+'''syntax:''' ''ok, err = tcpsock:setoption(option, value?)''
 
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*''
 
-This function is added for [http://w3.impa.br/~diego/software/luasocket/tcp.html LuaSocket] API compatibility and does nothing for now. Its functionality will be implemented in future.
+This function is added for [http://w3.impa.br/~diego/software/luasocket/tcp.html LuaSocket] API compatibility and does nothing for now. Its functionality is implemented <code>v0.10.18</code>.
 
 This feature was first introduced in the <code>v0.5.0rc1</code> release.
 
+In case of success, it returns <code>true</code>. Otherwise, it returns nil and a string describing the error.
+
+The <code>option</code> is a string with the option name, and the value depends on the option being set:
+
+* <code>keepalive</code>
+
+: Setting this option to true enables sending of keep-alive messages on
+: connection-oriented sockets. Make sure the <code>connect</code> function
+: had been called before, for example,
+
+    <geshi lang="lua">
+    local ok, err = tcpsock:setoption("keepalive", true)
+    if not ok then
+        ngx.say("setoption keepalive failed: ", err)
+    end
+    </geshi>
+* <code>reuseaddr</code>
+
+: Enabling this option indicates that the rules used in validating addresses
+: supplied in a call to bind should allow reuse of local addresses. Make sure
+: the <code>connect</code> function had been called before, for example,
+
+    <geshi lang="lua">
+    local ok, err = tcpsock:setoption("reuseaddr", 0)
+    if not ok then
+        ngx.say("setoption reuseaddr failed: ", err)
+    end
+    </geshi>
+* <code>tcp-nodelay</code>
+
+: Setting this option to true disables the Nagle's algorithm for the connection.
+: Make sure the <code>connect</code> function had been called before, for example,
+
+    <geshi lang="lua">
+    local ok, err = tcpsock:setoption("tcp-nodelay", true)
+    if not ok then
+        ngx.say("setoption tcp-nodelay failed: ", err)
+    end
+    </geshi>
+* <code>sndbuf</code>
+
+: Sets the maximum socket send buffer in bytes. The kernel doubles this value
+: (to allow space for bookkeeping overhead) when it is set using setsockopt().
+: Make sure the <code>connect</code> function had been called before, for example,
+
+    <geshi lang="lua">
+    local ok, err = tcpsock:setoption("sndbuf", 1024 * 10)
+    if not ok then
+        ngx.say("setoption sndbuf failed: ", err)
+    end
+    </geshi>
+* <code>rcvbuf</code>
+
+: Sets the maximum socket receive buffer in bytes. The kernel doubles this value
+: (to allow space for bookkeeping overhead) when it is set using setsockopt. Make
+: sure the <code>connect</code> function had been called before, for example,
+
+    <geshi lang="lua">
+    local ok, err = tcpsock:setoption("rcvbuf", 1024 * 10)
+    if not ok then
+        ngx.say("setoption rcvbuf failed: ", err)
+    end
+    </geshi>
+
+NOTE: Once the option is set, it will become effective until the connection is closed. If you know the connection is from the connection pool and all the in-pool connections already have called the setoption() method with the desired socket option state, then you can just skip calling setoption() again to avoid the overhead of repeated calls, for example,
+
+<geshi lang="lua">
+    local count, err = tcpsock:getreusedtimes()
+    if not count then
+        ngx.say("getreusedtimes failed: ", err)
+        return
+    end
+
+    if count == 0 then
+        local ok, err = tcpsock:setoption("rcvbuf", 1024 * 10)
+        if not ok then
+            ngx.say("setoption rcvbuf failed: ", err)
+            return
+        end
+    end
+</geshi>
+
+These options described above are supported in <code>v0.10.18</code>, and more options will be implemented in future.
+
 == tcpsock:setkeepalive ==
 
 '''syntax:''' ''ok, err = tcpsock:setkeepalive(timeout?, size?)''