kqueue bindings for lua
luarocks install kqueue
it returns true
if the kqueue is usable.
Returns
ok:boolean
:true
on if the kqueue is usable.
create a new kqueue instance.
Returns
kq:kqueue
: kqueue instance.err:string
: error string.errno:number
: error number.
return the number of registered events.
return the string representation of the kqueue instance.
close the kqueue descriptor that holds by the kqueue instance. free the event-list that holds by the kqueue instance.
disabled any events that have occurred and renew the file descriptor held by the kqueue instance.
NOTE: this method should be called after forking the process. additionally, you need to invoke the renew
method of the event instance that was created by the kqueue
instance.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
create a new kqueue.event
instance.
Returns
ev:kqueue.event
:kqueue.event
instance.
wait for events. it consumes all remaining events before waiting for new events.
Parameters
sec:number
: timeout in seconds. if the value isnil
or<0
then it waits forever.
Returns
n:number?
: the number of events, ornil
if error occurred.err:string
: error string.errno:number
: error number.
Example
local kqueue = require('kqueue')
local kq = assert(kqueue.new())
-- register a new event for the file descriptor 0 (stdin)
local ev = assert(kq:new_event())
assert(ev:as_read(0))
-- wait until stdin is readable
local n, err, errno = kq:wait()
if err then
print(err, errno)
return
end
print('n:', n)
consume the occurred event.
NOTE:
- if error occurred, the
udata
will be treated as the error message, and thedisabled
will be treated as error number. - if it is a one-shot event, the event is automatically unregistered and
disabled
is set totrue
. - if the event flag is set to
EV_EOF
orEV_ERROR
, thedisabled
andeof
are set totrue
.
Returns
ev:kqueue.event?
:kqueue.event
instance, ornil
if error occurred.udata:any
: userdata stored in the event.disabled:boolean
:true
if the event has been disabled.eof:boolean
:true
if theEV_EOF
orEV_ERROR
flag is set.err:string
: error message fromstrerror(errno)
.errno:number
: error numbererrno
.
Example
local kqueue = require('kqueue')
local kq = assert(kqueue.new())
-- register a new event for the file descriptor 0 (stdin)
local ev = assert(kq:new_event())
assert(ev:as_read(0, 'hello'))
-- wait until stdin is readable
local n, err, errno = kq:wait()
if err then
print('error:', err, errno)
return
end
print('n:', n)
-- consume the event
local occurred, udata, disabled, eof, err, errno = kq:consume()
if err then
print('error:', err, errno)
elseif ocurred then
print('event occurred:', ocurred, udata)
end
kqueue.event
instance is used to register the following events.
- Read event: it watches the file descriptor until it becomes readable.
- Write event: it watches the file descriptor until it becomes writable.
- Signal event: it watches the signal until it becomes occurred.
- Timer event: it watches the timer until it becomes expired.
rewatch the event. if the kq
is specified then it rewatch the event with the specified kqueue instance.
Parameters
kq:kqueue
:kqueue
instance.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
return true
if the event trigger is level trigger.
Returns
ok:boolean
:true
if the event trigger is level trigger.
change the event trigger to level trigger.
NOTE: the level trigger is a trigger that is activated while the state of the target is active.
Returns
ok:boolean
:true
on success.
return true
if the event trigger is edge trigger.
Returns
ok:boolean
:true
if the event trigger is edge trigger.
change the event trigger to edge trigger.
NOTE: the edge trigger is a trigger that is activated only when the state of the target changes from inactive to active.
Returns
ok:boolean
:true
on success.
return true
if the event type is one-shot event.
Returns
ok:boolean
:true
if the event type is one-shot event.
change the event type to one-shot event.
NOTE: the one-shot event is a event that is automatically removed after the event is activated.
Returns
ok:boolean
:true
on success.
register a event that watches the file descriptor until it becomes readable.
this method is change the meta-table of the ev
to kqueue.read
.
Parameters
fd:number
: file descriptor.udata:any
: user data.
Returns
ev:kqueue.read?
:kqueue.read
instance that is changed the meta-table of theev
, ornil
if error occurred.err:string
: error string.errno:number
: error number.
Example
local kqueue = require('kqueue')
local kq = assert(kqueue.new())
-- register a new event for the file descriptor 0 (stdin)
local ev = assert(kq:new_event())
assert(ev:as_read(0, 'stdin is readable'))
-- wait until stdin is readable
local n, err, errno = kq:wait()
if err then
print(err, errno)
return
end
print('n:', n)
-- consume the event
while true do
local occurred, udata, disabled, eof, err, errno = kq:consume()
if err then
print('error:', err, errno)
elseif not occurred then
break
end
print('event occurred:', occurred, udata)
end
register a event that watches the file descriptor until it becomes writable.
this method is change the meta-table of the ev
to kqueue.write
.
Parameters
fd:number
: file descriptor.udata:any
: user data.
Returns
ev:kqueue.write?
:kqueue.write
instance that is changed the meta-table of theev
, ornil
if error occurred.err:string
: error string.errno:number
: error number.
Example
local kqueue = require('kqueue')
local kq = assert(kqueue.new())
-- register a new event for the file descriptor 1 (stdout)
local ev = assert(kq:new_event())
assert(ev:as_write(1, 'stdout is writable'))
-- wait until stdout is writable
local n, err, errno = kq:wait()
if err then
print(err, errno)
return
end
print('n:', n)
-- consume the event
while true do
local occurred, udata, disabled, eof, err, errno = kq:consume()
if err then
print('error:', err, errno)
elseif not occurred then
break
end
print('event occurred:', occurred, udata)
end
register a event that watches the signal until it becomes occurred.
this method is change the meta-table of the ev
to kqueue.signal
.
Parameters
signo:number
: signal number.udata:any
: user data.
Returns
ev:kqueue.signal?
:kqueue.signal
instance that is changed the meta-table of theev
, ornil
if error occurred.err:string
: error string.errno:number
: error number.
Example
local signal = require('signal')
local kqueue = require('kqueue')
local kq = assert(kqueue.new())
-- register a new event for the signal SIGINT
local ev = assert(kq:new_event())
assert(ev:as_signal(signal.SIGINT, 'SIGINT occurred'))
-- wait until SIGINT is occurred
signal.block(signal.SIGINT)
local n, err, errno = kq:wait()
if err then
print(err, errno)
return
end
print('n:', n)
-- consume the event
while true do
local occurred, udata, disabled, eof, err, errno = kq:consume()
if err then
print('error:', err, errno)
elseif not occurred then
break
end
print('event occurred:', occurred, udata)
end
register a event that watches the timer until it becomes expired.
this method is change the meta-table of the ev
to kqueue.timer
.
Parameters
ident:number
: timer identifier.sec:number
: timer interval in seconds.udata:any
: user data.
Returns
ev:kqueue.timer?
:kqueue.timer
instance that is changed the meta-table of theev
, ornil
if error occurred.err:string
: error string.errno:number
: error number.
Example
local kqueue = require('kqueue')
local kq = assert(kqueue.new())
-- register a new event for the timer
local ev = assert(kq:new_event())
assert(ev:as_timer(123, 0.150, 'timer expired after 150 milliseconds'))
-- wait until the timer is expired
local n, err, errno = kq:wait()
if err then
print(err, errno)
return
end
print('n:', n)
-- consume the event
while true do
local occurred, udata, disabled, eof, err, errno = kq:consume()
if errno then
print('error:', udata, errno)
elseif not occurred then
break
end
print('event occurred:', occurred, udata)
end
the following methods are common methods of the kqueue.read
, kqueue.write
, kqueue.signal
and kqueue.timer
instances.
return the event type.
Returns
t:string
: event type as follows.event
: type of theepoll.event
instance.read
: type of theepoll.read
instance.write
: type of theepoll.write
instance.signal
: type of theepoll.signal
instance.timer
: type of theepoll.timer
instance.
rewatch the event. if the kq
is specified then it rewatch the event with the specified kqueue instance.
Parameters
kq:kqueue
:kqueue
instance.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
revert the event to the kqueue.event
instance. if the event is enabled then it disable the event.
Returns
ev:kqueue.event?
:kqueue.event
instance that is reverted the meta-table of theev
, ornil
if error occurred.err:string
: error string.errno:number
: error number.
watch the event.
NOTE: the event is managed by its type and a unique identifier pair. If this pair has already been watched, then the method will return false
.
kqueue.read
: file descriptor used as the identifier.kqueue.write
: file descriptor used as the identifier.kqueue.signal
: signal number used as the identifier.kqueue.timer
: timer identifier used as the identifier.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
unwatch the event.
NOTE: if the event is enabled then it disable the event.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
return true
if the event is enabled (watching).
Returns
ok:boolean
:true
if the event is enabled (watching).
return true
if the event is occurred with EV_EOF
or EV_ERROR
flag.
Returns
ok:boolean
:true
if the event is occurred withEV_EOF
orEV_ERROR
flag.
return true
if the event trigger is level trigger.
Returns
ok:boolean
:true
if the event trigger is level trigger.
change the event trigger to level trigger.
NOTE: if the event is enabled, it can not be changed.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
return true
if the event trigger is edge trigger.
Returns
ok:boolean
:true
if the event trigger is edge trigger.
change the event trigger to edge trigger.
NOTE: if the event is enabled, it can not be changed.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
return true
if the event type is one-shot event.
Returns
ok:boolean
:true
if the event type is one-shot event.
change the event type to one-shot event.
NOTE: if the event is enabled, it can not be changed.
Returns
ok:boolean
:true
on success.err:string
: error string.errno:number
: error number.
return the identifier of the event.
Returns
ident:number
: identifier of the event.
set or return the user data of the event.
if the udata
is specified then it set the user data of the event and return the previous user data.
Returns
udata:any
: user data of the event.
get the information of the specified event.
NOTE: if the EV_ERROR
flag is present in the flags, then the data
treated as the errno
.
Parameters
event:string
: event name as follows.registered
: return the information of the event that is registered.occurred
: return the information of the event that is occurred.
Returns
info:table
: information of the event.ident:number
: identifier of the event.flags:string
: flags of the event.fflags:string
: filter flags of the event.data:number
: data of the event.udata:any
: user data of the event.edge:boolean
:true
if the event trigger is edge trigger.oneshot:boolean
:true
if the event type is one-shot event.
err:string
: error string.errno:number
: error number.