#ifndef __RING_BUFFER_H
#define __RING_BUFFER_H

#include <stdint.h>

/*
 * Type definitions
 */
typedef void* rb_handle_t;

/*
 * Public API
 */
// Allocate a new ring buffer.
// Parameters:
//  - size      - size of buffer in bytes
// Returns:
//  - ring buffer handle on success
//  - NULL on out-of-memory
rb_handle_t rb_allocate(uint32_t size);

// Free ring buffer.
// Parameters:
//  - rb        - ring buffer
// Remarks:
//  - no-op if rb is NULL
void rb_free(rb_handle_t rb);

// Get free size of ring buffer.
// Parameters:
//  - rb        - ring buffer
// Returns:
//  - count of free bytes in ring buffer
uint32_t rb_get_free_bytes(rb_handle_t rb);


// RAW ACCESS. Get count of bytes you can read in one call.
// Parameters:
//  - rb        - ring buffer
// Returns:
//  - count of bytes you can copy from rb_raw_read_ptr()
// Remarks:
//  - you may read until this function returns zero
uint32_t rb_raw_read_size(rb_handle_t rb);

// RAW ACCESS. Get pointer to the area you can read from.
// Parameters:
//  - rb        - ring buffer
// Returns:
//  - memory you can read from (use rb_raw_read_size to get max read size)
const void *rb_raw_read_ptr(rb_handle_t rb);

// RAW ACCESS. Notify the ring buffer that a read has happened.
// Parameters:
//  - rb        - ring buffer
//  - size      - how much bytes were read
// Returns:
//  - count of bytes you can still read
// Remarks:
//  - no-op if size == 0 (but return value is still valid)
//  - this function will not check for overflow
uint32_t rb_raw_read_advance(rb_handle_t rb, uint32_t size);


// RAW ACCESS. Get count of bytes you can write in one call.
// Parameters:
//  - rb        - ring buffer
// Returns:
//  - count of bytes you can write to rb_raw_write_ptr()
// Remarks:
//  - you may write until this function returns zero
uint32_t rb_raw_write_size(rb_handle_t rb);

// RAW ACCESS. Get pointer to the area you can write to.
// Parameters:
//  - rb        - ring buffer
// Returns:
//  - memory you can write to (use rb_raw_write_size to get max write size)
void *rb_raw_write_ptr(rb_handle_t rb);

// RAW ACCESS. Notify the ring buffer that a write has happened.
// Parameters:
//  - rb        - ring buffer
//  - size      - how much bytes were written
// Returns:
//  - count of bytes you can still write
// Remarks:
//  - no-op if size == 0 (but return value is still valid)
//  - this function will not check for overflow
uint32_t rb_raw_write_advance(rb_handle_t rb, uint32_t size);

#endif