.\" Copyright (c) 2018-2022, OARC, Inc.
.\" All rights reserved.
.\"
.\" This file is part of dnsjit.
.\"
.\" dnsjit is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" dnsjit is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with dnsjit.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsjit.core.thread 3 "1.2.3" "dnsjit"
.SH NAME
dnsjit.core.thread \- POSIX thread with separate Lua state
.SH SYNOPSIS
  local thr = require("dnsjit.core.thread").new()
  thr:start(function(thr)
      print("Hello from thread")
      print("got:", thr:pop(), " = ", thr:pop(3))
  end)
  thr:push("value from main", 1, 2, 3)
  thr:stop()
.SH DESCRIPTION
Start a new POSIX thread with it's own Lua state.
Sharable objects can be passed to the thread by pushing and poping them of
the thread stack.
The Thread object and any other objects passed to the thread needs to be
kept alive as long as the thread is running.
.SS Functions
.TP
.BR Thread.new "()"
Create a new Thread object.
.TP
.BR Thread:log "()"
Return the Log object to control logging of this instance or module.
.TP
.BR Thread:start "(func)"
Start the thread and execute the given function in a separate Lua state,
first argument to the function will be the Thread object that created it.
Returns 0 on success.
.TP
.BR Thread:stop "()"
Wait for the thread to return.
Returns 0 on success.
.TP
.BR Thread:push "(...)"
Push string(s), number(s) or sharable object(s) onto the thread stack so
they can be retrieved inside the thread using
.IR pop() .
The sharable object(s) needs to be kept alive as long as the thread is
running, strings and numbers are copied.
.TP
.BR Thread:pop "(num)"
Pop value(s) off the thread stack, should only be called within the thread.
If
.I num
is not given then one value is poped.
Returns nil if no values are left on the stack.
.SH SEE ALSO
.BR dnsjit.core.channel (3)
.SH AUTHORS and CONTRIBUTORS
Jerry Lundström (DNS-OARC),
Tomáš Křížek (CZ.NIC),
Petr Špaček (ISC)
.LP
Maintained by DNS-OARC
.LP
.RS
.I https://www.dns-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fIhttps://github.com/DNS-OARC/dnsjit/issues\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fIadmin@dns-oarc.net\fP
.RE
.LP