/**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

#pragma once
#include "dusk.h"

typedef uint_fast16_t ref_t;

typedef struct reflist_s reflist_t;

typedef struct reflist_s {
  ref_t *array;
  uint_fast16_t max;
  uint_fast16_t count;
  ref_t refNext;

  void *user;

  void (*onNotEmpty)(reflist_t *list);
  void (*onFull)(reflist_t *list);
  void (*onAdd)(reflist_t *list, const ref_t ref);
  void (*onRemove)(reflist_t *list, const ref_t ref);
  void (*onEmpty)(reflist_t *list);
} reflist_t;

/**
 * Initialize a reference list. Reference lists just hold a list of references
 * that are "holding on to" a given object/resource.
 * 
 * @param list The reference list to initialize.
 * @param array The array to use as backing storage for the list.
 * @param max The maximum number of references the list can hold.
 */
void refListInit(
  reflist_t *list,
  ref_t *array,
  const uint_fast16_t max
);


/**
 * Lock a reference in the list. This will return a new reference ID that can be
 * used to access the locked reference.
 * 
 * @param list The reference list to lock a reference in.
 * @return The locked reference ID, or 0 if the list is full.
 */
ref_t refListLock(reflist_t *list);

/**
 * Unlock a reference in the list. This will free up the reference ID for
 * reuse.
 * 
 * @param list The reference list to unlock a reference in.
 * @param ref The reference ID to unlock.
 */
void refListUnlock(reflist_t *list, const ref_t ref);

/**
 * Checks if the reference list is full.
 * 
 * @param list The reference list to check.
 * @return true if the list is full, false otherwise.
 */
bool_t refListIsFull(const reflist_t *list);

/**
 * Checks if the reference list is empty.
 * 
 * @param list The reference list to check.
 * @return true if the list is empty, false otherwise.
 */
bool_t refListIsEmpty(const reflist_t *list);