/* buf.h — page-aligned, refcounted buffer pool.
 *
 * This is the spine of the zero-copy data path. One physical buffer is filled
 * by recv (io_uring registered buffer), decrypted in place, hashed in place by
 * a worker thread, then written to disk via O_DIRECT or sent via SEND_ZC — the
 * same pages throughout, never memcpy'd.
 *
 * Ownership model (ABA-free without tagging):
 *   - naut_buf_get() pops from the freelist and is SINGLE-CONSUMER: only the
 *     pool's owning reactor thread may call it.
 *   - naut_buf_put()/naut_buf_ref() are MULTI-PRODUCER: any thread (e.g. a hash
 *     worker that finished with a buffer) may call them. put() pushes back onto
 *     the freelist only on the 1->0 refcount transition.
 * Because only the owner pops, a buffer in flight is never re-pushed by another
 * thread, so the Treiber-stack pop has no ABA hazard.
 */
#ifndef NAUT_BUF_H
#define NAUT_BUF_H

#include "naut/common.h"

typedef struct naut_bufpool naut_bufpool;

typedef struct naut_buf {
    _Atomic uint32_t refcnt;     /* live references; 0 => on freelist        */
    uint32_t         len;        /* bytes of valid payload in data[]          */
    uint32_t         cap;        /* == pool block_size                        */
    uint32_t         idx;        /* index within the pool (for registered bufs)*/
    struct naut_buf *fnext;      /* freelist link (owner-thread access only)  */
    naut_bufpool    *pool;
    uint8_t         *data;       /* page-aligned, cap bytes                    */
} naut_buf;

/* block_size must be a multiple of NAUT_PAGE (O_DIRECT alignment).
 * If use_hugepages, the data slab is mmap'd with MAP_HUGETLB (falls back to
 * normal pages if unavailable). */
naut_bufpool *naut_bufpool_create(uint32_t block_size, uint32_t block_count,
                                  bool use_hugepages);
naut_bufpool *naut_bufpool_create_on_node(uint32_t block_size,
                                          uint32_t block_count,
                                          bool use_hugepages,
                                          int numa_node);
void          naut_bufpool_destroy(naut_bufpool *p);

/* Owner thread only. Returns NULL when exhausted (caller applies backpressure).
 * Returned buffer has refcnt==1 and len==0. */
naut_buf *naut_buf_get(naut_bufpool *p) NAUT_MUST_USE;

/* Any thread. */
NAUT_INLINE void naut_buf_ref(naut_buf *b) {
    atomic_fetch_add_explicit(&b->refcnt, 1, memory_order_relaxed);
}
void naut_buf_put(naut_buf *b);

/* Introspection (approximate under concurrency). */
uint32_t naut_bufpool_capacity(const naut_bufpool *p);
uint32_t naut_bufpool_available(const naut_bufpool *p);

/* Base of the contiguous data slab + total bytes — used to register the whole
 * region with io_uring as a single fixed-buffer area. */
void *naut_bufpool_slab(const naut_bufpool *p, size_t *out_bytes);

#endif /* NAUT_BUF_H */