.\" 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.channel 3 "1.2.3" "dnsjit"
.SH NAME
dnsjit.core.channel \- Send data to another thread
.SH SYNOPSIS
  local chan = require("dnsjit.core.channel").new()
  local thr = require("dnsjit.core.thread").new()
  thr:start(function(thr)
      local chan = thr:pop()
      local obj = chan:get()
      ...
  end)
  thr:push(chan)
  chan:put(...)
  chan:close()
  thr:stop()
.SH DESCRIPTION
A channel can be used to send data to another thread, this is done by
putting a pointer to the data into a wait-free and lock-free ring buffer
(concurrency kit).
The channel uses the single producer, single consumer model (SPSC) so
there can only be one writer and one reader.
.SS Attributes
.TP
int closed
Is 1 if the channel has been closed.
.SS Functions
.TP
.BR Channel.new "(capacity)"
Create a new Channel, use the optional
.I capacity
to specify the capacity of the channel (buffer).
Capacity must be a power-of-two greater than or equal to 4.
Default capacity is 2048.
.TP
.BR Channel:log "()"
Return the Log object to control logging of this instance or module.
.TP
.BR Channel:share "()"
Return information to use when sharing this object between threads.
.TP
.BR Channel:put "(obj)"
Put an object into the channel, if the channel is full then it will
stall and wait until space becomes available.
Object may be nil.
.TP
.BR Channel:put "(obj)"
Try and put an object into the channel.
Returns 0 on success.
.TP
.BR Channel:get "()"
Get an object from the channel, if the channel is empty it will wait until
an object is available.
Returns nil if the channel is closed or if a nil object was explicitly put
into the channel.
.TP
.BR Channel:try_get "()"
Try and get an object from the channel.
Returns nil if there was no objects to get.
.TP
.BR Channel:size "()"
Return number of enqueued objects.
.TP
.BR Channel:full "()"
Returns true when channel is full.
.TP
.BR Channel:close "()"
Close the channel.
.TP
.BR Channel:receive "()"
Return the C functions and context for receiving objects.
.TP
.BR Channel:receiver "(o)"
Set the receiver to pass objects to.
NOTE; The channel keeps no reference of the receiver, it needs to live as
long as the channel does.
.TP
.BR Channel:run "()"
Retrieve all objects from the channel and send it to the receiver.
.SH SEE ALSO
.BR dnsjit.core.thread (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