Skip to content

Define consistent qsize, empty, full, and maxsize semantics #23

Description

@polyrand

Context

LiteQueue's size methods count different message states:

  • qsize() counts READY and LOCKED messages.
  • empty() counts only READY messages.
  • full() and the persistent maxsize trigger count only READY messages.
  • DONE and FAILED rows remain stored but do not count toward queue size.

On commit 2b82ede, a queue with one locked message returned empty() == True and qsize() == 1.

The README now explains that maxsize limits ready messages, but it does not define how qsize() and empty() relate to locked work.

Why implement this

Users rely on these methods for worker shutdown, health checks, backpressure, and metrics. Contradictory answers make it easy to stop workers while jobs are still active or to report misleading queue depth.

Proposed direction

Choose and document one model. A simple option is:

  • Make qsize() report the ready backlog.
  • Keep empty() equivalent to qsize() == 0.
  • Keep full() and maxsize based on ready backlog.
  • Add explicit methods such as locked_count(), active_count(), and stored_count() for other views.

If backwards compatibility requires qsize() to include locked work, rename or add methods so each state set is explicit.

Acceptance criteria

  • qsize(), empty(), full(), and maxsize follow one documented model.
  • Locked, failed, completed, and mixed-state queues have explicit counts.
  • The README includes an example with active locked work.
  • Tests cover each status and mixed-status queues.
  • Any compatibility change is called out in release notes.
  • make test passes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions