#if !defined(__XCELIST_H__)
#define __XCELIST_H__ 1

/*
 * Intrusive doubly-linked list.
 *
 * A list entry must have its `forw` and `back` pointers as its first two
 * members so that a user-defined node (e.g. `struct { void* forw; void* back;
 * ...payload... }`) can be safely cast to `xcelist_entry_t*`.
 *
 * The list head (`xcelist_t`) is itself layout-compatible with an entry: its
 * `forw` field points to the first entry (or back to itself when empty) and
 * its `back` field points to the last entry. `numEnts` tracks the entry count.
 *
 * This replaces the previously external `basiclib/list.h` (extralib) with the
 * minimal subset of functionality actually used in-tree.
 */

typedef struct _xcelist_entry {
    struct _xcelist_entry* forw;
    struct _xcelist_entry* back;
} xcelist_entry_t;

typedef struct _xcelist {
    /* head sentinel: must mirror xcelist_entry_t layout (forw/back first) */
    xcelist_entry_t* forw;
    xcelist_entry_t* back;
    int              numEnts;
    char*            name;
} xcelist_t;

/* Create an empty list. `name` is copied and may be NULL. Returns NULL on OOM. */
extern xcelist_t* list_create(const char* name);

/* Destroy a list. Does not free the entries; caller owns them. */
extern void list_destroy(xcelist_t* list);

/* Append `entry` to the back (tail) of `list`. */
extern void list_insert_entry_back(xcelist_t* list, xcelist_entry_t* entry);

/* Unlink `entry` from `list`. Does not free `entry`. */
extern void list_entry_remove(xcelist_t* list, xcelist_entry_t* entry);

#endif