Luv reference manual luvref

LibUV in Lua luv-libuv-in-lua

TCP Echo Server Example luv-tcp-echo-server-example

local uv = require("luv") -- "luv" when stand-alone, "uv" in luvi apps

local server = uv.new_tcp()
assert(server:bind("127.0.0.1", 1337))
server:listen(128, function (err)
  assert(not err, err)
  local client = uv.new_tcp()
  server:accept(client)
  client:read_start(function (err, chunk)
    assert(not err, err)
    if chunk then
      client:write(chunk)
    else
      client:shutdown()
      client:close()
    end
  end)
end)
print("TCP server listening at 127.0.0.1 port 1337")
uv.run() -- an explicit run call is necessary outside of luvit

Module Layout luv-module-layout

Functions vs Methods luv-functions-vs-methods

Synchronous vs Asynchronous Functions luv-synchronous-vs-asynchronous-functions

Pseudo-Types luv-pseudo-types

Contents luv-contents

Constants luv-constants

-- signal start with string input
uv.signal_start("sigterm", function(signame)
  print(signame) -- string output: "sigterm"
end)

-- signal start with integer input
uv.signal_start(uv.constants.SIGTERM, function(signame)
  print(signame) -- string output: "sigterm"
end)

Address Families luv-address-families

Signals luv-signals

Socket Types luv-socket-types

TTY Modes luv-tty-modes

FS Modification Times luv-fs-modification-times

Error Handling luv-error-handling uv.errno

Version Checking luv-version-checking

uv_loop_t - Event loop luv-event-loop uv_loop_t

uv.loop_configure("block_signal", "sigprof")

-- Example usage of uv.walk to close all handles that aren't already closing.
uv.walk(function (handle)
  if not handle:is_closing() then
    handle:close()
  end
end)

uv_req_t - Base request luv-base-request

uv_handle_t - Base handle luv-base-handle

Reference counting luv-reference-counting

uv_timer_t - Timer handle luv-timer-handle

-- Creating a simple setTimeout wrapper
local function setTimeout(timeout, callback)
  local timer = uv.new_timer()
  timer:start(timeout, 0, function ()
    timer:stop()
    timer:close()
    callback()
  end)
  return timer
end

-- Creating a simple setInterval wrapper
local function setInterval(interval, callback)
  local timer = uv.new_timer()
  timer:start(interval, interval, function ()
    callback()
  end)
  return timer
end

-- And clearInterval
local function clearInterval(timer)
  timer:stop()
  timer:close()
end

uv_prepare_t - Prepare handle luv-prepare-handle

local prepare = uv.new_prepare()
prepare:start(function()
  print("Before I/O polling")
end)

uv_check_t - Check handle luv-check-handle

local check = uv.new_check()
check:start(function()
  print("After I/O polling")
end)

uv_idle_t - Idle handle luv-idle-handle

local idle = uv.new_idle()
idle:start(function()
  print("Before I/O polling, no blocking")
end)

uv_async_t - Async handle luv-async-handle

local async
async = uv.new_async(function()
  print("async operation ran")
  async:close()
end)

async:send()

uv_poll_t - Poll handle luv-poll-handle

uv_signal_t - Signal handle luv-signal-handle

uv_process_t - Process handle luv-process-handle

local stdin = uv.new_pipe()
local stdout = uv.new_pipe()
local stderr = uv.new_pipe()

print("stdin", stdin)
print("stdout", stdout)
print("stderr", stderr)

local handle, pid = uv.spawn("cat", {
  stdio = {stdin, stdout, stderr}
}, function(code, signal) -- on exit
  print("exit code", code)
  print("exit signal", signal)
end)

print("process opened", handle, pid)

uv.read_start(stdout, function(err, data)
  assert(not err, err)
  if data then
    print("stdout chunk", stdout, data)
  else
    print("stdout end", stdout)
  end
end)

uv.read_start(stderr, function(err, data)
  assert(not err, err)
  if data then
    print("stderr chunk", stderr, data)
  else
    print("stderr end", stderr)
  end
end)

uv.write(stdin, "Hello World")

uv.shutdown(stdin, function()
  print("stdin shutdown", stdin)
  uv.close(handle, function()
    print("process closed", handle, pid)
  end)
end)

uv_stream_t - Stream handle luv-stream-handle

server:listen(128, function (err)
  local client = uv.new_tcp()
  server:accept(client)
end)

stream:read_start(function (err, chunk)
  if err then
    -- handle read error
  elseif chunk then
    -- handle data
  else
    -- handle disconnect
  end
end)

server:listen(128, function (err)
  local client = uv.new_tcp()
  server:accept(client)
end)

stream:read_start(function (err, chunk)
  if err then
    -- handle read error
  elseif chunk then
    -- handle data
  else
    -- handle disconnect
  end
end)

uv_tcp_t - TCP handle luv-tcp-handle

-- Simple read/write with tcp
local fds = uv.socketpair(nil, nil, {nonblock=true}, {nonblock=true})

local sock1 = uv.new_tcp()
sock1:open(fds[1])

local sock2 = uv.new_tcp()
sock2:open(fds[2])

sock1:write("hello")
sock2:read_start(function(err, chunk)
  assert(not err, err)
  print(chunk)
end)

local client = uv.new_tcp()
client:connect("127.0.0.1", 8080, function (err)
  -- check error and carry on.
end)

local client = uv.new_tcp()
client:connect("127.0.0.1", 8080, function (err)
  -- check error and carry on.
end)

uv_pipe_t - Pipe handle luv-pipe-handle

local pipe = uv.new_pipe(false)

pipe:bind('/tmp/sock.test')

pipe:listen(128, function()
  local client = uv.new_pipe(false)
  pipe:accept(client)
  client:write("hello!\n")
  client:close()
end)

-- Simple read/write with pipe_open
local fds = uv.pipe({nonblock=true}, {nonblock=true})

local read_pipe = uv.new_pipe()
read_pipe:open(fds.read)

local write_pipe = uv.new_pipe()
write_pipe:open(fds.write)

write_pipe:write("hello")
read_pipe:read_start(function(err, chunk)
  assert(not err, err)
  print(chunk)
end)

uv_tty_t - TTY handle luv-tty-handle

-- Simple echo program
local stdin = uv.new_tty(0, true)
local stdout = uv.new_tty(1, false)

stdin:read_start(function (err, data)
  assert(not err, err)
  if data then
    stdout:write(data)
  else
    stdin:close()
    stdout:close()
  end
end)

uv_udp_t - UDP handle luv-udp-handle

-- If client:connect(...) was not called
local addr = { ip = "127.0.0.1", port = 1234 }
client:try_send2({
  { data = "Message 1", addr = addr },
  { data = "Message 2", addr = addr },
})

-- If client:connect(...) was called
client:try_send2({
  { data = "Message 1" },
  { data = "Message 2" },
})

-- If client:connect(...) was not called
local addr = { ip = "127.0.0.1", port = 1234 }
client:try_send2({
  { data = "Message 1", addr = addr },
  { data = "Message 2", addr = addr },
})

-- If client:connect(...) was called
client:try_send2({
  { data = "Message 1" },
  { data = "Message 2" },
})

uv_fs_event_t - FS Event handle luv-fs-event-handle

uv_fs_poll_t - FS Poll handle luv-fs-poll-handle

File system operations luv-file-system-operations

local function readFileSync(path)
  local fd = assert(uv.fs_open(path, "r", 438))
  local stat = assert(uv.fs_fstat(fd))
  local data = assert(uv.fs_read(fd, stat.size, 0))
  assert(uv.fs_close(fd))
  return data
end

local data = readFileSync("main.lua")
print("synchronous read", data)

local function readFile(path, callback)
  uv.fs_open(path, "r", 438, function(err, fd)
    assert(not err, err)
    uv.fs_fstat(fd, function(err, stat)
      assert(not err, err)
      uv.fs_read(fd, stat.size, 0, function(err, data)
        assert(not err, err)
        uv.fs_close(fd, function(err)
          assert(not err, err)
          return callback(data)
        end)
      end)
    end)
  end)
end

readFile("main.lua", function(data)
  print("asynchronous read", data)
end)

Thread pool work scheduling luv-thread-pool-work-scheduling

local function work_callback(a, b)
  return a + b
end

local function after_work_callback(c)
  print("The result is: " .. c)
end

local work = uv.new_work(work_callback, after_work_callback)

work:queue(1, 2)

-- output: "The result is: 3"

DNS utility functions luv-dns-utility-functions

Threading and synchronization utilities luv-threading-and-synchronization-utilities