queue

type Item struct {
	Id   string
	Task *task.Task
	// Score is the priority score of the item. The lower the socre, the higher the priority.
	// It is desired to fetch items with the lowest score first.
	// The score is determined per queue kind as following:
	//  - Fifo: Incremental sequence number.
	//  - Priority: The priority of the task.
	//  - Scheduled: Epoch in millisecond of the scheduled time.
	Score    int64
	QueuedAt time.Time
}

type Kind int

type Operator interface {
	// Push pushes a task item into the queue.
	Push(ctx context.Context, item *Item) error

	// Pop pops the Item object with the highest priority.
	//  it returns ErrNotFound when there's no items in the queue.
	Pop(ctx context.Context, group task.Group) (*Item, error)

	// PopScheduled pops an Item object that met the schedule.
	//  it returns ErrNotFound when there's no items in the queue.
	//  it returns ErrNotAvailable when there's no available items in the queue(the scheduled time not yet reached).
	PopScheduled(ctx context.Context, group task.Group) (*Item, error)
}

type Option struct {
	// TaskGroup identifies the task group.
	TaskGroup task.Group
	// Kind is the kind of the queue.
	Kind Kind
	// PollInterval is the desired wait period between consecutive `Pop()` function calls for available item polling.
	PollInterval time.Duration
	// Operator is the QueueOperator.
	Operator Operator
}

type Queue interface {
	// Push pushes a task into the queue.
	Push(ctx context.Context, task *task.Task) (*Item, error)

	// Pop pops the Item object with the highest priority.
	//  it returns ErrNotFound when there's no items in the queue.
	//  it returns ErrNotAvailable when there's no available items in the queue(the scheduled time not yet reached).
	Pop(ctx context.Context) (*Item, error)

	// TryPop pops the Item object with the highest priority.
	// This function can wait up to `timeout` until there's an item become available.
	//  it returns ErrNotFound when there's no items in the queue.
	//  it returns ErrNotAvailable when there's no available items in the queue(the scheduled time not yet reached).
	TryPop(ctx context.Context, timeout time.Duration) (*Item, error)
}