From 17a91a3a85c4db48532c5f067d553dd141dc7cec Mon Sep 17 00:00:00 2001 From: Cooper Larson <26559155+cooperlarson@users.noreply.github.com> Date: Fri, 2 Aug 2024 12:19:30 -0600 Subject: [PATCH] Update README.md --- README.md | 68 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 80f5aed..128682a 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,40 @@ -# EARLY RELEASE | ACTIVELY IN DEVELOPMENT -## A performant bounded priority deque for specialized use-cases, highly volatile at the moment but will be stable in short future. - -### Highlighting the need: -* missing from the std C++ lib and as standalone lightweight library on major C++ package managers such as Conan (used for gtest in this project) -* Inspired for use in multithreaded ball tree construction and query contexts for TSP solutions with maximum performance. -* The core data structure on this has changed nearly 10 times since I started this a month ago (extracted from larger TSP project). - * sorted vector w/binary search - * vector min heap - * unordered-set - * ordered set - * priority-queue - * deque - * ordered set of indexed linked-list nodes - * *CURRENT: circular buffer based vector - * minimizes destructor calls, previously profiled to be a huge weakness - * allows O(1) pop from front of the priority deque, previously required a heapify or swap and bubble sort action that was often nearing O(n) - -### This will be a header only, very lean, and highly-performant library. - -## It is the crux of my C++ TSP solution at the moment serving roles in multiple facets of the optimization process (BallTree construction + NN queries, 2opt/3opt multithreaded task bins, etc): -* "Safety rails" are removed by design when compiled for release - * will throw exceptions and print debug info in debug mode - * otherwise there are no protections, for maximum performance in tight multithreaded loops. - * thread safety is programmers responsibility -* the operator+=() merge/extend method is in dev but will be very efficient for merging deques from multiple local threaded futures into a single deque, preventing the necessity of using mutex with the right multi-threaded task architecture. -* The smaller the parent deque and the more data culled, the faster the performance, under my own testing at least... -### More info coming soon... +# Bounded Priority Deque + +A highly efficient, single-header C++ library implementing a bounded priority deque with a focus on performance and versatility through templating. This library utilizes a circular buffer, chosen for its robust performance characteristics. + +## Release Status: Early Development + +This project is currently in active development and is subject to significant changes. However, a stable release is anticipated in the near future. + +## Motivation + +The bounded priority deque addresses a notable gap in the standard C++ library and fills a niche not currently catered to by lightweight libraries available on major C++ package managers such as Conan. This project emerged from complex requirements in multi-threaded ball tree constructions and Traveling Salesman Problem (TSP) solution optimizations. + +### Evolution of the Core Data Structure + +The design of this deque has undergone numerous iterations, each aimed at enhancing performance and efficiency: + +- Sorted vector with binary search +- Vector-based min heap +- Unordered set +- Ordered set +- Priority queue +- Deque +- Ordered set of indexed linked-list nodes +- **Current Implementation:** Circular buffer-based vector + - This minimizes destructor calls, addressing a previously identified performance bottleneck. + - It enables O(1) time complexity for pop operations from the front of the deque, a significant improvement over previous methods that approached O(n) complexity. + +## Key Features + +- **Single-Header Library:** Streamlined and efficient, suitable for integration into various C++ projects without the overhead of additional compilation units. +- **Optimized for TSP Solutions:** Crucial to various facets of the TSP optimization process, including BallTree construction, nearest neighbor queries, and multithreaded 2-opt and 3-opt tasks. +- **Developer Control:** Intentionally designed without "safety rails" in release mode to maximize performance: + - Throws exceptions and provides debug information in debug mode. + - Expects the programmer to manage thread safety, accommodating highly efficient multithreaded operations. +- **Efficient Merging Capability:** The `operator+=()` for merging deques aims to facilitate efficient integration of results from multiple threads without the need for mutex locks, given appropriate task architecture. +- **Performance Insights:** Preliminary testing suggests performance improves as the size of the parent deque decreases and more data is culled. + +## Future Directions + +Further information and updates on this library will be provided as development progresses. Interested users and contributors are encouraged to keep an eye on repository updates for the latest enhancements and stability improvements.