dragonflight/services/framecache/client/fc_client.h

/**
 * fc_client.h — Consumer-side framecache client library.
 *
 * Usage:
 *   fc_consumer_t *c = fc_consumer_open("deltacast-zampp3-0");
 *   fc_frame_ref_t ref;
 *   while (fc_consumer_read(c, &ref, 2000) == FC_OK) {
 *       // ref.data valid until next fc_consumer_read call
 *       process_frame(ref.data, ref.size, ref.pts_us);
 *   }
 *   fc_consumer_close(c);
 *
 * Each consumer tracks its own read_cursor — multiple consumers on the same
 * slot are fully independent and never block each other or the writer.
 *
 * If a consumer falls more than ring_depth frames behind the writer its cursor
 * is snapped to the latest frame and FC_DROPPED is returned once.
 */
#pragma once

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Return codes */
#define FC_OK       0    /* valid frame returned in ref */
#define FC_TIMEOUT  1    /* no new frame within timeout_ms — ref not populated */
#define FC_DROPPED  2    /* valid frame returned in ref, BUT one or more older
                          * frames were skipped first (consumer fell behind).
                          * ref IS populated — caller should USE the frame. */
#define FC_LAPPED   3    /* the copy was overwritten mid-read (writer lapped the
                          * consumer during memcpy). ref NOT populated — caller
                          * should call fc_consumer_read again. */
#define FC_ERROR   -1

typedef struct fc_consumer fc_consumer_t;

typedef struct {
    const uint8_t *data;    /* pointer to a CONSUMER-OWNED copy of the frame —
                             * stable until the next fc_consumer_read() call.
                             * (Previously a zero-copy pointer into the shm ring,
                             * which the writer could overwrite mid-use when it
                             * lapped a slow consumer. We now copy into the
                             * consumer's own buffer and re-validate the cursor
                             * AFTER the copy, so a lapped frame is discarded
                             * rather than streamed corrupt.) */
    uint32_t       size;    /* bytes */
    uint64_t       pts_us;  /* presentation timestamp (microseconds) */
    uint64_t       wall_us; /* wall clock at write time (microseconds) */
    uint64_t       seq;     /* write_cursor value for this frame */
} fc_frame_ref_t;

/**
 * Open a consumer handle for the named slot.
 * Polls the slot shm file until it appears (up to wait_ms milliseconds).
 * Returns NULL if slot not found within wait_ms or on error.
 */
fc_consumer_t *fc_consumer_open(const char *slot_id, uint64_t wait_ms);

/**
 * Read the next frame.
 * Blocks up to timeout_ms waiting for a new frame (via semaphore).
 * Returns FC_OK, FC_TIMEOUT, FC_DROPPED, or FC_ERROR.
 * On FC_OK or FC_DROPPED the ref fields are populated.
 */
int fc_consumer_read(fc_consumer_t *c, fc_frame_ref_t *ref, uint64_t timeout_ms);

/** Close the consumer handle. Does NOT destroy the slot. */
void fc_consumer_close(fc_consumer_t *c);

/** Current write_cursor of the slot (approximate — no lock). */
uint64_t fc_consumer_write_cursor(fc_consumer_t *c);

/** Frames dropped by this consumer since open. */
uint64_t fc_consumer_dropped(fc_consumer_t *c);

#ifdef __cplusplus
}
#endif