create descriptor pair for interprocess communication.
$ luarocks install os-pipe
the functions/methods are return the error object created by https://github.com/mah0x211/lua-errno module.
create instances of os.pipe.reader
and os.pipe.writer
.
local pipe = require('os.pipe')
local r, w, err = pipe()
Parameters
nonblock:boolean
: setO_NONBLOCK
flag to each descriptor.
Returns
r:os.pipe.reader
: instance ofos.pipe.reader
.w:os.pipe.writer
: instance ofos.pipe.writer
.err:error
: error object.
os.pipe.writer
write a string to the associated descriptor.
Parameters
s:string
: string data.
Returns
n:integer
: number of bytes written.err:error
: error object.again:boolean
:nil
, ortrue
iferrno
isEAGAIN
,EWOULDBLOCK
orEINTR
.
NOTE
write
syscall may raise the SIGPIPE
signal. use the nosigpipe module or something similar to prevent this signal from killing the process.
Usage
-- you must install the nosigpipe module with `luarocks install nosigpipe`
-- to prevent SIGPIPE signals.
require('nosigpipe')
-- you must install dump module with `luarocks install dump`
local dump = require('dump')
local pipe = require('os.pipe')
local r, w, err = pipe(true)
assert(err == nil, err)
-- write a message
local n, err, again = w:write('hello')
print(dump({n, err, again}))
-- {
-- [1] = 5
-- }
-- write a message until an again becomes true
repeat
n, err, again = w:write('hello')
assert(err == nil, err)
until again == true
-- write returns nil after reader is closed
r:close()
n, err, again = w:write('hello')
print(dump({n, err, again}))
-- {
-- [2] = "./example.lua:29: in main chunk: [EPIPE:32][write] Broken pipe"
-- }
-- write returns err after writer is closed
w:close()
n, err, again = w:write('hello')
print(dump({n, err, again}))
-- {
-- [2] = "./example.lua:39: in main chunk: [EBADF:9][write] Bad file descriptor"
-- }
read bytes of data from the associated descriptor.
Parameters
bufsize:integer
: number of bytes read (default: 4096
).
Returns
s:string
: data read from associated descriptor, ornil
ifread
syscall returned0
or an error occurred.err:error
: error object.again:boolean
: nil ortrue
iferrno
isEAGAIN
,EWOULDBLOCK
orEINTR
.
NOTE: all return values will be nil
if the number of bytes read is 0
.
Usage
require('nosigpipe')
-- you must install the nosigpipe module with `luarocks install nosigpipe`
-- to prevent SIGPIPE signals.
local dump = require('dump')
-- you must install dump module with `luarocks install dump`
local pipe = require('os.pipe')
local r, w, err = pipe(true)
assert(err == nil, err)
-- read returns again (true)
local s, err, again = r:read()
print(dump({s, err, again}))
-- {
-- [3] = true
-- }
-- read a message from writer
w:write('hello')
s, err, again = r:read()
print(dump({s, err, again}))
-- {
-- [1] = "hello"
-- }
-- read a buffered message even writer is closed
w:write('world!')
w:close()
s, err, again = r:read()
print(dump({s, err, again}))
-- {
-- [1] = "world!"
-- }
-- read returns nil after writer is closed
s, err, again = r:read()
print(dump({s, err, again}))
-- {}
-- read returns err after reader is closed
r:close()
s, err, again = r:read()
print(dump({s, err, again}))
-- {
-- [2] = "./example.lua:65: in main chunk: [EBADF:9][read] Bad file descriptor"
-- }
os.pipe.reader
and os.pipe.writer
instances have the following common methods.
- enabled, err = os.pipe.reader:nonblock( [enabled] )
- enabled, err = os.pipe.writer:nonblock( [enabled] )
if an error occurs, return nil
and err
.
Parameters
enabled:boolean
: setO_NONBLOCK
flag to enabled.
Returns
enabled:boolean
: ifenabled
parameter passed, its returns a previous status.err:error
: error object.
- fd = os.pipe.reader:fd()
- fd = os.pipe.writer:fd()
Returns
fd:integer
: file descriptor. returns-1
afterp:close()
is called.
- ok, err = os.pipe.reader:close()
- ok, err = os.pipe.writer:close()
Returns
ok:boolean
:true
on success.err:error
: error object.
os.pipe.io
is a utility object that wraps os.pipe.reader
and os.pipe.writer
and provides a bi-directional interface. also, this interface uses lua-gpoll to implicitly handle non-blocking operations.
create instance of os.pipe.io
.
local pipeio = require('os.pipe.io')
local p, err = pipeio(true)
Parameters
nonblock:boolean
: setO_NONBLOCK
flag to each descriptor.
Returns
p:pipe.io
: instance ofos.pipe.io
.err:error
: error object.
read bytes of data from the associated descriptor.
Parameters
bufsize:integer
: number of bytes read (default: 4096
).sec:number
: timeout seconds. ifnil
or<0
, wait forever.
Returns
s:string
: data read from associated descriptor, ornil
ifread
syscall returned0
or an error occurred.err:error
: error object.timeout:boolean
:true
on timed-out.
NOTE: all return values will be nil
if the number of bytes read is 0
.
write a string to the associated descriptor.
Parameters
s:string
: string data.sec:number
: timeout seconds. ifnil
or<0
, wait forever.
Returns
n:integer
: number of bytes written.err:error
: error object.timeout:boolean
:true
on timed-out.
close the os.pipe.reader
.
Returns
ok:boolean
:true
on success.err:error
: error object.
close the os.pipe.writer
.
Returns
ok:boolean
:true
on success.err:error
: error object.
close both os.pipe.reader
and os.pipe.writer
.
Returns
ok:boolean
:true
on success.err:error
: error object.