%%
%% %CopyrightBegin%
%%
%% Copyright Ericsson AB 2017. All Rights Reserved.
%%
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%% http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
%%
%% %CopyrightEnd%
%%
-module(prim_buffer).
-export([on_load/0]).
%% This is a mutable binary buffer that helps break out buffering logic from
%% NIFs/drivers, which is often the only thing that prevents the C code from
%% being reduced to bare system call wrappers.
%%
%% All operations in this file are thread-unsafe and risk crashing the emulator
%% if you're not careful.
-export([new/0, size/1, wipe/1, read/2, read_iovec/2, write/2, skip/2]).
-export([find_byte_index/2]).
-export([try_lock/1, unlock/1]).
-type prim_buffer() :: term().
%% Controls when to copy rather than extract sub-binaries from the buffer,
%% reducing the risk of small reads keeping a large binary alive.
-define(COPYING_READ_LIMIT, 512).
%% Reads that fit into heap binaries are always copied since the cost of
%% peeking binaries that short is largely equivalent to copying.
-define(ERL_ONHEAP_BIN_LIMIT, 64).
on_load() ->
case erlang:load_nif(atom_to_list(?MODULE), 0) of
ok -> ok
end.
-spec new() -> prim_buffer().
new() ->
erlang:nif_error(undef).
-spec size(Buffer :: prim_buffer()) -> non_neg_integer().
size(_Buffer) ->
erlang:nif_error(undef).
%% Reads data as a binary from the front of the buffer. This will almost always
%% result in copying so it should be avoided unless you absolutely must have a
%% binary.
-spec read(Buffer :: prim_buffer(), Size :: non_neg_integer()) -> binary().
read(Buffer, Size) when Size =< ?ERL_ONHEAP_BIN_LIMIT ->
copying_read(Buffer, Size);
read(Buffer, Size) when Size > ?ERL_ONHEAP_BIN_LIMIT ->
iolist_to_binary(read_iovec(Buffer, Size)).
%% Reads data as an erlang:iovec() binary from the front of the buffer,
%% avoiding copying if reasonable.
-spec read_iovec(Buffer, Size) -> IOVec when
Buffer :: prim_buffer(),
Size :: non_neg_integer(),
IOVec :: erlang:iovec().
read_iovec(Buffer, Size) when Size =< ?ERL_ONHEAP_BIN_LIMIT ->
[copying_read(Buffer, Size)];
read_iovec(Buffer, Size) when Size > ?ERL_ONHEAP_BIN_LIMIT ->
Head = peek_head(Buffer),
HeadSize = byte_size(Head),
if
(HeadSize - Size) > ?COPYING_READ_LIMIT, Size =< ?COPYING_READ_LIMIT ->
[copying_read(Buffer, Size)];
HeadSize > Size ->
skip(Buffer, Size),
{First, _Rest} = split_binary(Head, Size),
[First];
HeadSize < Size ->
skip(Buffer, HeadSize),
[Head | read_iovec(Buffer, Size - HeadSize)];
HeadSize =:= Size ->
skip(Buffer, Size),
[Head]
end.
%% Writes an erlang:iovec() to the back of the buffer.
-spec write(Buffer :: prim_buffer(), IOVec :: erlang:iovec()) -> ok.
write(_Buffer, _IOVec) ->
erlang:nif_error(undef).
%% Removes data from the front of the buffer without reading it.
-spec skip(Buffer :: prim_buffer(), Size :: non_neg_integer()) -> ok.
skip(_Buffer, _Size) ->
erlang:nif_error(undef).
-spec wipe(Buffer :: prim_buffer()) -> ok.
wipe(Buffer) ->
skip(Buffer, prim_buffer:size(Buffer)).
%% Finds the start-index of the first occurence of Needle, for implementing
%% read_line and similar.
-spec find_byte_index(Buffer, Needle) -> Result when
Buffer :: prim_buffer(),
Needle :: non_neg_integer(),
Result :: {ok, non_neg_integer()} |
not_found.
find_byte_index(_Buffer, _Needle) ->
erlang:nif_error(undef).
%% Attempts to take a unique lock on the buffer. Failure handling is left to
%% the user.
-spec try_lock(Buffer :: prim_buffer()) -> acquired | busy.
try_lock(_Buffer) ->
erlang:nif_error(undef).
-spec unlock(Buffer :: prim_buffer()) -> ok.
unlock(_Buffer) ->
erlang:nif_error(undef).
%% Unexported helper functions:
%% Reads data from the front of the buffer, returning a copy of the data to
%% avoid holding references.
-spec copying_read(Buffer :: prim_buffer(), Size :: non_neg_integer()) -> binary().
copying_read(_Buffer, _Size) ->
erlang:nif_error(undef).
%% Returns the binary at the front of the buffer without modifying the buffer.
-spec peek_head(Buffer :: prim_buffer()) -> binary().
peek_head(_Buffer) ->
erlang:nif_error(undef).
