# ludic.base/queue.ludic - a mechanic reports what HAPPENED as facts in a queue it owns, and the
# game drains it in a later phase. First in, first out; nothing here rolls dice or reorders.
export property Queue<T> {
  items: []T = null
  tag: QueueTag = null
  none: []T = null            # what draining an empty queue hands back, never pushed to
  spare: []T = null           # the list the last drain handed out: cleared and reused by the next
  ring: []T = null            # the facts' records, used again once no list holds them (queue_ring.ludic)
  ring_at: int = 0
}
# what a queue says about itself, whatever it holds: its name and how many facts wait in it
export property QueueTag {
  name: string = ""
  pending: int = 0
}

# BaseState is the system runner's (system.ludic). A queue keeps its own count, so pushing and
# draining one takes only the state that owns the queue.
export state BaseState {
  cs_list: []System = null
}

# a queue; the name is only for core_undrained
export function queue_new<T>(name: string) -> Queue<T> {
  let q = new Queue<T>
  q.items = new []T
  q.tag = new QueueTag
  q.tag.name = name
  q.none = new []T
  q.spare = new []T
  q.ring = new []T
  return q
}

export function q_push<T>(q: Queue<T>, v: T) -> void {
  kept_push(q.items, v)
  q.tag.pending = len(q.items)
}

# the facts in the order they were pushed; the queue is empty afterwards. Ludic frees nothing, so
# a drain allocates nothing: the queue keeps two lists and hands one out while the other fills, and
# an empty drain hands back one shared empty list. What a drain returns is good until the NEXT
# drain of the same queue - read it, never push to it, never keep it.
export function q_drain<T>(q: Queue<T>) -> []T {
  if len(q.items) == 0 { return q.none }
  let out = q.items
  List.clear(q.spare)
  q.items = q.spare
  q.spare = out
  q.tag.pending = 0
  return out
}

export function q_len<T>(q: Queue<T>) -> int { return len(q.items) }

# in place: the live list was never handed out (a drain gives its list away and starts another)
export function q_clear<T>(q: Queue<T>) -> void {
  List.clear(q.items)
  q.tag.pending = 0
}

# pool's records the queue no longer holds - neither waiting nor handed out by the last drain - put
# into out (cleared first): what a package may fill again instead of making a new record per fact
export function q_unheld<T>(q: Queue<T>, pool: []T, out: []T) -> int {
  List.clear(out)
  for i in 0 .. len(pool) {
    let r = pool[i]
    var held = false
    for j in 0 .. len(q.items) { if q.items[j] == r { held = true } }
    for j in 0 .. len(q.spare) { if q.spare[j] == r { held = true } }
    if not held { kept_push(out, r) }
  }
  return len(out)
}

# a queue's tag, for core_undrained: queues of different facts in one list
export function q_tag<T>(q: Queue<T>) -> QueueTag { return q.tag }

# the names of the given queues still holding facts, into `out` (cleared first) and counted; ask it
# at the end of a frame, where a fact left behind is a route nobody wrote
export function core_undrained(tags: []QueueTag, out: []string) -> int {
  List.clear(out)
  for i in 0 .. len(tags) {
    if tags[i] != null and tags[i].pending > 0 { kept_push(out, tags[i].name) }
  }
  return len(out)
}