#ifndef PTXMC_PIPELINE_H_INCLUDED
#define PTXMC_PIPELINE_H_INCLUDED

#include <assert.h>
#include <stddef.h>
#include <stdarg.h>

#include "config.h"

#define PIPELINE_STAGE ATTR_WUR ATTR_ACCESS((read_only, 1))
#define PIPELINE_INIT ATTR_ACCESS((read_only, 1))
#define PIPELINE_CLEANUP ATTR_ACCESS((read_only, 1))

typedef struct ptx__pipeline_ctx_tag ptx_pipeline_ctx_t;
typedef struct ptx__pipeline_tag ptx_pipeline_t;

typedef int (ptx_pipeline_proc_t)(const ptx_pipeline_ctx_t * /*ctx*/, const void * /*data*/, size_t /*len*/) PIPELINE_STAGE;
typedef int (ptx_pipeline_init_proc_t)(const char * /*name*/, void ** /*ppuser*/, va_list /*init_args*/) PIPELINE_INIT;
typedef void (ptx_pipeline_cleanup_proc_t)(const char * /*name*/, void * /*puser*/) PIPELINE_CLEANUP;

struct ptx_pipeline_stage_funcs {
  ptx_pipeline_proc_t *handler;
  ptx_pipeline_init_proc_t *init;
  ptx_pipeline_cleanup_proc_t *cleanup;
};

#ifdef MODULE
#define MODEXP extern
#else
#define MODEXP \
__attribute__((visibility("protected")))
#endif

/* allocates a new pipeline, with space for `initial_size' new stages. */
MODEXP ptx_pipeline_t *ptx_pipeline_new(size_t initial_size) ATTR_WUR ATTR_MALLOC() ATTR_MALLOC((ptx_pipeline_free, 1));

/* frees an existing pipeline stage. note that this will call the cleanup function in the stages as well. */
void ptx_pipeline_free(ptx_pipeline_t *pl);

/* adds `stage' with `name' to `pipeline' after `after'
 * returns: number of stages added to pipeline (0 or 1), or -1 if there was an allocation or initialization error. */
int ptx_pipeline_add_after(ptx_pipeline_t *pipeline, const struct ptx_pipeline_stage_funcs *stage, const char *name, const char *after, ...);
/* adds `stage' with `name' to `pipeline' before `before'
 * returns: number of stages added to pipeline (0 or 1), or -1 if there was an allocation or initialization error. */
int ptx_pipeline_add_before(ptx_pipeline_t *pipeline, const struct ptx_pipeline_stage_funcs *stage, const char *name, const char *before, ...);

/* TODO: could theoretically have versions of the above functions that don't defensively copy `name' */

/* returns: number of stages removed from pipeline */
int ptx_pipeline_remove_stage(ptx_pipeline_t *pipeline, const char *name);

/* this pointer is guaranteed to be valid as long as the pipeline context is active (i.e., within this handler function)
 * If you need to access user data of a stage from outside of a handler function, TODO */
void **ptx_pipeline_ctx_get_user(const ptx_pipeline_ctx_t *ctx);
const char *ptx_pipeline_ctx_get_name(const ptx_pipeline_ctx_t *ctx);

int ptx_pipeline_ctx_next(const ptx_pipeline_ctx_t *ctx, const void *nextdata, size_t nextsize);

void ptx_pipeline_ctx_diag(const ptx_pipeline_ctx_t *ctx, int lvl, const char *fmt, ...) ATTR_FORMAT((printf, 3, 4)); /* TODO: pipeline stages should be able to send diagnostic messages */

int ptx_pipeline_handle(ptx_pipeline_t *pipeline, const void *data, size_t sz); /* TODO: diagnostic */

#endif /* include guard */