Refactoring and Optimizing the WorkQueue Go Library: Design, Implementation, and Performance Evaluation

I am Lee, a veteran with 17 years of experience in the IT industry, sharing the recent optimization and refactor of the WorkQueue project, including the motivations, identified pain points, and the overall redesign strategy.

Event Background : Users reported ordering issues and performance problems in the original WorkQueue (v1) implementation, especially with the traditional four‑ary heap that could not guarantee stable ordering.

Pain Point Analysis identified five major problems: unstable sorting heap, confusing interface design, mismatched functionality, low code quality, and tangled architecture.

Refactor Goals focused on redesigning a stable sorting heap, simplifying interfaces, improving functionality, and enhancing code quality and architecture.

1. Sorting Heap

The new heap is implemented with a red‑black tree to ensure stability and performance while using a linked‑list based structure to avoid memory fragmentation. Sample insertion code:

func (tree *RBTree) insert(node *lst.Node) { /* ... */ }

Deletion logic is also provided:

func (tree *RBTree) delete(node *lst.Node) { /* ... */ }

Performance benchmarks show nanosecond‑level operation times for Push , Pop , and Remove methods.

2. Linked List

A custom doubly linked list replaces container/list , adding traversal, swap, and slice conversion features. Example of the Range method:

func (l *List) Range(fn func(node *Node) bool) { /* ... */ }

Benchmarks demonstrate comparable performance to the standard library.

3. Interface Design

The v2 version redesigns interfaces following Go best practices (interface segregation, dependency inversion). UML class diagrams guide the implementation. Interfaces such as Queue , PriorityQueue , DelayingQueue , and RateLimitingQueue are defined with clear method sets.

4. Functional Design

Priority queues now follow the classic model without a "sorting window", while delaying queues use a fixed 300 ms window with a time.Ticker for batch processing of expired tasks. This balances latency and throughput.

5. Performance Testing

Extensive benchmarks compare Queue , DelayingQueue , PriorityQueue , and RateLimitingQueue across put, get, and combined operations, confirming the efficiency of the new implementations.

Quick Start Guide

Import the package, create a queue with wkq.NewQueue(nil) , put and get elements, and shut down the queue when done. A complete example program demonstrates a consumer goroutine processing items from the queue.

Conclusion : The refactor delivers a simpler, more efficient, stable, and extensible WorkQueue library, validated by real‑world usage and thorough testing.