Skip to content
Snippets Groups Projects
  • Nikita Pettik's avatar
    c53a45ec
    lua: introduce interface for prbuf · c53a45ec
    Nikita Pettik authored
    Simply add Lua wrappers for recently introduced prbuf.
    
    Introduce new buffer (in addition to ibuf) - prbuf. "pr" stands for
    "partitioned ring-". It save all metadata in the same memory chunk
    provided for storage, so it can be completely restored from the 'raw'
    memory. API:
    
    ```
    -- mem is a chunk of raw (char *) memory, of size mem_size.
    -- It is used for data storage. Note that available space is of less
    -- size due to prbuf metadata overhead.
    -- Returns handle to prbuf.
    --
    require('buffer').prbuf_create(mem, mem_size)
    
    -- mem is a chunk of memory, which contains already created prbuf.
    -- It implies that once prbuf_create() was called with the same memory.
    -- If mem does not contain valid buffer - raise an appropriate error.
    require('buffer').prbuf_open(mem)
    
    -- Returns continuous chunk of memory with given size. May return nil
    -- in case if requested chunk is too large. Note that after copying
    -- object to returned chunk, it should be committed with prbuf:commit();
    -- otherwise :prepare() may return the same chunk twice.
    prbuf:prepare(size)
    
    -- Commits the last prepared chunk. Undefined behaviour in case of
    -- committing the same chunk twice.
    prbuf:commit()
    
    -- Create and return prbuf_iterator. Does not fail. Created iterator
    -- points to nowhere - it should be adjusted with :next() call to
    -- the first entry.
    prbuf:iterator_create()
    
    -- Advance iterator position. Returns prbuf_entry or nil in case
    -- iterator has reached the end. Entry consists of two members:
    -- size and ptr. The last one is an array of characters of given size.
    iterator:next()
    ```
    
     Usage examples:
    
    ```
    
    local ibuf = buffer.ibuf()
    local prbuf_size = 100
    local memory = ibuf:alloc(prbuf_size)
    local prbuf = buffer.prbuf_create(memory, prbuf_size)
    
    local sample_size = 4
    local raw = prbuf:prepare(4)
    if raw == nil then
        -- allocation size is too large, try smaller.
    end
    raw[0] = ...
    ...
    raw[3] = ...
    prbuf:commit()
    local prbuf_recovered = buffer.prbuf_open(memory)
    local iter = prbuf_recovered:iterator_create()
    local entry = iter:next()
    assert(tonumber(entry.size) == 4)
    -- Check values stored in the buffer.
    assert(entry.ptr[0] == ...)
    entry = iter:next()
    -- Our buffer has only one entry.
    assert(entry == nil)
    
    ```
    
    NO_DOC=<Feature for internal usage>
    NO_CHANGELOG=<Feature for internal usage>
    c53a45ec
    History
    lua: introduce interface for prbuf
    Nikita Pettik authored
    Simply add Lua wrappers for recently introduced prbuf.
    
    Introduce new buffer (in addition to ibuf) - prbuf. "pr" stands for
    "partitioned ring-". It save all metadata in the same memory chunk
    provided for storage, so it can be completely restored from the 'raw'
    memory. API:
    
    ```
    -- mem is a chunk of raw (char *) memory, of size mem_size.
    -- It is used for data storage. Note that available space is of less
    -- size due to prbuf metadata overhead.
    -- Returns handle to prbuf.
    --
    require('buffer').prbuf_create(mem, mem_size)
    
    -- mem is a chunk of memory, which contains already created prbuf.
    -- It implies that once prbuf_create() was called with the same memory.
    -- If mem does not contain valid buffer - raise an appropriate error.
    require('buffer').prbuf_open(mem)
    
    -- Returns continuous chunk of memory with given size. May return nil
    -- in case if requested chunk is too large. Note that after copying
    -- object to returned chunk, it should be committed with prbuf:commit();
    -- otherwise :prepare() may return the same chunk twice.
    prbuf:prepare(size)
    
    -- Commits the last prepared chunk. Undefined behaviour in case of
    -- committing the same chunk twice.
    prbuf:commit()
    
    -- Create and return prbuf_iterator. Does not fail. Created iterator
    -- points to nowhere - it should be adjusted with :next() call to
    -- the first entry.
    prbuf:iterator_create()
    
    -- Advance iterator position. Returns prbuf_entry or nil in case
    -- iterator has reached the end. Entry consists of two members:
    -- size and ptr. The last one is an array of characters of given size.
    iterator:next()
    ```
    
     Usage examples:
    
    ```
    
    local ibuf = buffer.ibuf()
    local prbuf_size = 100
    local memory = ibuf:alloc(prbuf_size)
    local prbuf = buffer.prbuf_create(memory, prbuf_size)
    
    local sample_size = 4
    local raw = prbuf:prepare(4)
    if raw == nil then
        -- allocation size is too large, try smaller.
    end
    raw[0] = ...
    ...
    raw[3] = ...
    prbuf:commit()
    local prbuf_recovered = buffer.prbuf_open(memory)
    local iter = prbuf_recovered:iterator_create()
    local entry = iter:next()
    assert(tonumber(entry.size) == 4)
    -- Check values stored in the buffer.
    assert(entry.ptr[0] == ...)
    entry = iter:next()
    -- Our buffer has only one entry.
    assert(entry == nil)
    
    ```
    
    NO_DOC=<Feature for internal usage>
    NO_CHANGELOG=<Feature for internal usage>