FreeBSD Manual Pages
open_nonblock(3) Arcan Lua API open_nonblock(3) NAME open_nonblock - Open a file in read or write mode for non-blocking I/O. SYNOPSIS blocktbl open_nonblock( vid:res ) open_nonblock( vid:res, bool:write ) open_nonblock( vid:res, bool:write, string:identifier=stream ) open_nonblock( vid:res, bool:write, string:identifier=stream, user- data:nbioud ) open_nonblock( string:res ) open_nonblock( string:res, bool:write ) DESCRIPTION Create or open the resource indicated by res in (default) read-mode or (if mode is provided, write mode) If res is a vid connected to a frameserver, either a streaming fifo session will be set up over the connection along with the corresponding _BCHUNK events or an pre-existing nonblock-io stream, nbioud , will be redirected to said client and the backing descriptor closed locally. The identifier argument can then be used to specify some client an- nounced type identifier, or one of the reserved "stdin", "stdout", "stderr". If res is a string, the initial character determines if it creates a FIFO (<) or a SOCKET (=). Unless a namespace is explicitly set and the namespace is marked as valid for IPC , FIFO s and SOCKET s will be created in the RESOURCE_APPL_TEMP namespace. For sockets, the write argument determines if the connection should be outbound (=true) or listening (=false). If the string starts with a valid namespace identifier and separator (alphanum:/) the identifier will first be matched to a user defined namespace (see list_namespaces ). If successful, FIFO s and normal resources return a table wih a close operation (which is activated on garbage collection unless called in beforehand) and a read or write function depending on the mode that the resource was opened in. The socket table is special in that it allows multiple connections. the initial table for a socket only has a close and an accept function. The accept function takes no arguments and returns a table in both read and write mode when there is a client waiting. The read(bool:nobuf, [arg]):str,bool function takes one optional argu- ment, nobuf which disables local buffering. The default behavior of the read function is otherwise to buffer until a full line, a fixed buffer size or eof has been encountered. It returns two values, a string (possibly empty) and a boolean indicating if the connection or file is still alive or not. It also supports two optional reading modes that are more convenient and faster than multiple calls to read. If [arg] is a lua function, it will be invoked as a callback(str:line, bool:eof) with each line in the current buffer along with information (eof) if the backing data store is still connected and has more data that could be read or arrive in the future (sockets, pipes) or not. If [arg] is a table, it will be treated as n indexed and new lines will be appending at the end of the table [#tbl+1] = line1; [#tbl+2] = line2; and so on. The lf_strip(bool) function affects read results to include or exclude a splitting linefeed if operating in linefeed mode. This is mainly an optimization to avoid additional string manipulation when linefeeds aren't desired in the resulting string. It is also possible to pass lf_strip(bool, str) where the first character of the string will be used to determine end of line. This can be used to manage ' ' separated sequenced strings. The write(buf, [callback(ok, gpublock)]):int,bool function takes a buffer string or table of buffer strings as argument and queues for writing. If a callback is provided, it will be triggered if writing en- counters a terminal state or all queued writes have been completed. Multiple subsequent write calls will add buffers to the queue, and the last provided callback will be the only one to fire. The callback form can also fail (returns 0, false) if the number of polled data sources exceed some system bound or if the source is not opened for writing. The queue processing status can be queried through the out- queue():count,queue with the returned count being accumulated bytes in total, and queue the current remaining queued bytes. These counters are flushed when the queue has finished processing and the callback is in- voked. The data_handler(callback(gpublock)):bool function sets a callback that will be invoked when the descriptor becomes available for reading. This will only fire once, and need to be re-armed by setting a new data_han- dler. This can fail if the number of polled data sources exceed some system bound, but there is at least one slot for data_handler calls. The gpublock argument in both write and data_handler indicates if the callback is triggered from a state where calls that would alter graph- ics pipeline state are permitted or would trigger undefined behaviour. This is likely to be set as the scheduler will try to defer I/O opera- tions to when it is blocked on rendering or scanning out to a display. If processing the data would cause modifications to the rendering pipeline state, it should then be buffered and handled in the pre- frame_pulse event handler. Some files support absolute and/or relative seeking. For relative seek- ing based on the current file position, call :seek(ofs):bool,int. To set an absolute file position, call set_position(pos):bool,int with negative values being treated as the offset from file end. Both forms return if the seek succeeded and the last known absolute file position. NOTES 1 Do note that input processing has soft realtime constraints, and care should be taken to avoid processing large chunks of data in one go as it may affect application responsiveness. 2 FIFO s and sockets that were created will be unlinked when the close method is called or when the table reference is garbage collected. EXAMPLE function open_nonblock0() a = open_nonblock("test.txt") if (a == nil) then return shutdown("couldn't open test.txt"); end end function main_clock_pulse() local line = a:read(); if (line ~= nil) then print(line); end end EXAMPLE function open_nonblock1() a = open_nonblock("=test", false) b = open_nonblock("=test", true) -- our reader, note the scoping and the closure here local counter = 20 local dh dh = function() local res, alive = a:read() if res then print("read:", res) counter = counter - 1 if alive and counter > 0 then a:data_handler(dh) return end end a:close() -- will close on error or if counter reaches 0 end a:data_handler(dh) end function main_clock_pulse() if CLOCK % 100 == 0 then local _, alive = b:write("sent at " .. tostring(CLOCK)) if not alive then return shutdown() end end end SEE ALSO: resource April 2025 open_nonblock(3)
NAME | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLE | EXAMPLE | SEE ALSO:
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=open_nonblock&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>