From 5036bf7d5006a6f1a4294b4a3b1f4120d39113ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20H=C3=B6gberg?= <john@erlang.org>
Date: Tue, 7 Nov 2017 09:31:24 +0100
Subject: Add enif_ioq_peek_head

This introduces a way to retrieve erlang terms from NIF IO queues
without having to resort to copying.

OTP-14797
---
 erts/doc/src/erl_nif.xml | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index ef3cdb89e9..23f0c66429 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -367,6 +367,8 @@ return term;</code>
             <c>enif_ioq_deq()</c></seealso></item>
             <item><seealso marker="#enif_ioq_peek">
             <c>enif_ioq_peek()</c></seealso></item>
+            <item><seealso marker="#enif_ioq_peek_head">
+            <c>enif_ioq_peek_head()</c></seealso></item>
             <item><seealso marker="#enif_inspect_iovec">
             <c>enif_inspect_iovec()</c></seealso></item>
             <item><seealso marker="#enif_free_iovec">
@@ -1683,8 +1685,7 @@ enif_inspect_iovec(env, max_elements, term, &amp;tail, &amp;iovec);
       <fsummary>Peek inside the IO Queue</fsummary>
       <desc>
         <p>Get the I/O queue as a pointer to an array of <c>SysIOVec</c>s.
-          It also returns the number of elements in <c>iovlen</c>.
-          This is the only way to get data out of the queue.</p>
+           It also returns the number of elements in <c>iovlen</c>.</p>
         <p>Nothing is removed from the queue by this function, that must be done
           with <seealso marker="#enif_ioq_deq"><c>enif_ioq_deq</c></seealso>.</p>
          <p>The returned array is suitable to use with the Unix system
@@ -1692,6 +1693,21 @@ enif_inspect_iovec(env, max_elements, term, &amp;tail, &amp;iovec);
       </desc>
     </func>
 
+    <func>
+      <name><ret>int</ret>
+      <nametext>enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size, ERL_NIF_TERM *bin_term)</nametext></name>
+      <fsummary>Peek the head of the IO Queue.</fsummary>
+      <desc>
+        <p>Get the head of the IO Queue as a binary term.</p>
+        <p>If <c>size</c> is not <c>NULL</c>, the size of the head is placed
+           there.</p>
+        <p>Nothing is removed from the queue by this function, that must be done
+           with <seealso marker="#enif_ioq_deq"><c>enif_ioq_deq</c></seealso>.</p>
+        <p>Returns <c>true</c> on success, or <c>false</c> if the queue is
+           empty.</p>
+      </desc>
+    </func>
+
     <func>
       <name><ret>size_t</ret>
       <nametext>enif_ioq_size(ErlNifIOQueue *q)</nametext></name>
-- 
cgit v1.2.3