openresty 常用API学习二

ngx_socket_tcp
函数原型: tcpsock = ngx.socket.tcp()
函数说明: 创建并返回一个TCP或者Unix域字节流(stream-oriented unix domain)套接字对象(即 cosocket 对象)
该对象支持以下方法
connect
sslhandshake
send
receive
close
settimeout
settimeouts
setoption
receiveany
receiveuntil
setkeepalive
getreusedtimes
对于任意的处于连接状态的 cosocket 对象，如果没有显示调用close()方法关闭它或者将其放入连接池(setkeepalive()设置放入连接池)，
在以下两种情况下，cosocket 将自动关闭
a.当前请求处理完成(即处理完一次请求之后，如果不放入连接池，那么该 cosocket 会自动关闭)
b.cosocket 生存周期结束，被 Lua GC 回收
强调:同一个 cosocket 对象同时被可以被一个 'reader light thread' 和 一个 'writer light thread' 操作，
但是不可以是两个'reader light thread(writer light thread)'同时对 cosocket 对象操作

 

tcpsock:connect
函数原型: ok, err = tcpsock:connect(host, port, options_table?)
函数说明: 尝试在不阻塞的情况下将连接到远程服务器
IP地址和域名都可以指定为主机参数。如果是域名，这个方法会使用Nginx core的动态解析器解析域名，不阻塞，需要在nginx.conf文件配置DNS服务器地址
[resolver 8.8.8.8;  # use Google's public DNS nameserver]
函数返回值: 失败返回nil或者错误信息;成功返回1

location /test {
     resolver 8.8.8.8;

     content_by_lua_block {
         local sock = ngx.socket.tcp()
         local ok, err = sock:connect("www.google.com", 80)
         if not ok then
             ngx.say("failed to connect to google: ", err)
             return
         end
         ngx.say("successfully connected to google!")
         sock:close()
     }
 }

 

tcpsock:setkeepalive
函数原型: ok, err = tcpsock:setkeepalive(timeout?, size?)   '?表示可选'
函数说明: 将当前套接字的连接立即放入cosocket内置的连接池中，并使其保持活动状态，直到其他connect方法调用请求它或关联的最大空闲超时过期为止。
timeout: 可用于指定当前连接的最大空闲超时（以毫秒为单位）。如果省略，将使用lua_socket_keepalive_timeout config指令中的默认设置。如果给定0值，
则超时时间间隔是无限的。
size: 可选参数(不推荐使用)，因为该模块的v0.10.14版本支持connect方法的pool_size选项。自从v0.10.14版本发布以来，
此选项仅在调用connect尚未创建连接池时生效。当此选项生效时（connect以前没有创建连接池），
它将指定连接池的大小并创建它。如果省略（并且之前没有创建池），则默认大小为lua_socket_pool_size指令的值。连接池可容纳最大大小的活动连接，
可供后续的connect调用重用，但请注意，池外已打开连接的总数没有上限。当连接池将超过其大小限制时，池中已存在的最近最少使用（保持活动）的连接将关闭，
以便为当前连接腾出空间。
注意，cosocket连接池是每个Nginx工作进程而不是每个Nginx服务器实例，因此这里指定的大小限制也适用于每个Nginx工作进程。
还请注意，一旦创建了连接池，就不能更改它的大小。
函数返回值: 失败返回nil或者错误信息;成功返回1

说明:
tcpsock:setkeepalive是将当期套接字放入连接池，此时cosocket对象会被释放，而linux套接字将会被连接池接管，
调用者不再需要关心cosocket的释放问题。当调用tcpsock:connect方法时，Linux套接字的权限会重新交还给调用者，
调用者必须负责cosocket的释放问题(即需要调用close方法)，此时如果想将当期套接字放入连接池，必须再次调用tcpsock:setkeepalive方法

 

tcpsock:getreusedtimes
函数原型: count, err = tcpsock:getreusedtimes()
函数说明: 此方法返回当前连接的（成功）重用次数。如果出现错误，它将返回nil和一个描述错误的字符串。
如果当前连接不是来自于连接池，该方法将会返回0。此方法可以用于确定当前连接是否来自池

 

tcpsock:receive
函数原型: data, err, partial = tcpsock:receive(pattern?)
函数说明: 根据读取模式或大小从连接的套接字接收数据(非阻塞)。
如果成功，则返回接收到的数据；如果发生错误，则返回nil，其中包含一个描述错误和迄今为止接收到的部分数据的字符串。
模式可以是以下任何一种
a.'*a': 从套接字读取，直到连接关闭。不执行行尾翻译；
b.'*l': 从套接字读取一行文本。该行以LF字符（ASCII 10）结尾，也可以前面加一个CR字符（ASCII 13）。CR和LF字符不包括在返回行中。
实际上，模式忽略了所有的CR字符。这是默认模式；
c.number: 从套接字读取指定数量的字节。