From fce831266500e266f673e90ae4d94ed52d73e6b8 Mon Sep 17 00:00:00 2001 From: orxfun Date: Wed, 19 Nov 2025 18:36:23 +0100 Subject: [PATCH 1/6] advertise MSRV --- Cargo.toml | 1 + README.md | 43 ++++++++++++++++++++++--------------------- 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index b422d51..ad8f229 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,6 +9,7 @@ license = "MIT OR Apache-2.0" repository = "https://github.com/orxfun/orx-priority-queue/" keywords = ["priority", "queue", "heap", "dary", "binary"] categories = ["algorithms", "data-structures", "mathematics", "no-std"] +rust-version = "1.88" [features] default = ["std"] diff --git a/README.md b/README.md index 9497351..ae30b50 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,11 @@ [![orx-priority-queue crate](https://img.shields.io/crates/v/orx-priority-queue.svg)](https://crates.io/crates/orx-priority-queue) [![orx-priority-queue crate](https://img.shields.io/crates/d/orx-priority-queue.svg)](https://crates.io/crates/orx-priority-queue) [![orx-priority-queue documentation](https://docs.rs/orx-priority-queue/badge.svg)](https://docs.rs/orx-priority-queue) +[![MSRV](https://img.shields.io/badge/MSRV-1.88.0-blue)](https://releases.rs/docs/1.88.0/) Priority queue traits and high performance d-ary heap implementations. -> **no-std**: This crate supports **no-std**; however, *std* is added as a default feature. Please include with **no-default-features** for no-std use cases: `cargo add orx-priority-queue --no-default-features`. +> **no-std**: This crate supports **no-std**; however, _std_ is added as a default feature. Please include with **no-default-features** for no-std use cases: `cargo add orx-priority-queue --no-default-features`. ## A. Priority Queue Traits @@ -19,8 +20,9 @@ See [DecreaseKey](https://github.com/orxfun/orx-priority-queue/blob/main/docs/De ## B. d-ary Heap Implementations d-ary implementations are generalizations of the binary heap; i.e., binary heap is a special case where `D=2`. It is advantageous to have a parametrized d; as for instance, in the benchmarks defined here, `D=4` outperforms `D=2`. -* With a large d: number of per level comparisons increases while the tree depth becomes smaller. -* With a small d: each level requires fewer comparisons while the tree with the same number of nodes is deeper. + +- With a large d: number of per level comparisons increases while the tree depth becomes smaller. +- With a small d: each level requires fewer comparisons while the tree with the same number of nodes is deeper. Further, three categories of d-ary heap implementations are introduced. @@ -32,8 +34,8 @@ This is the basic d-ary heap implementing `PriorityQueue`. It is the default cho This is a d-ary heap paired up with a positions array and implements `PriorityQueueDecKey`. -* It requires the nodes to implement `HasIndex` trait which is nothing but `fn index(&self) -> usize`. Note that `usize`, `u64`, etc., already implements `HasIndex`. -* Further, it requires to know the maximum index that is expected to enter the queue. In other words, candidates are expected to come from a closed set. +- It requires the nodes to implement `HasIndex` trait which is nothing but `fn index(&self) -> usize`. Note that `usize`, `u64`, etc., already implements `HasIndex`. +- Further, it requires to know the maximum index that is expected to enter the queue. In other words, candidates are expected to come from a closed set. Once these conditions are satisfied, it **performs significantly faster** than the alternative decrease key queues. @@ -51,30 +53,29 @@ This is the most general decrease-key queue that provides the open-set flexibili In addition, queue implementations are provided in this crate for the following external data structures: -* `std::collections::BinaryHeap<(N, K)>` implements only `PriorityQueue`, -* `priority_queue:PriorityQueue` implements both `PriorityQueue` and `PriorityQueueDecKey` - * requires `--features impl_priority_queue` - * or `--features impl_all` +- `std::collections::BinaryHeap<(N, K)>` implements only `PriorityQueue`, +- `priority_queue:PriorityQueue` implements both `PriorityQueue` and `PriorityQueueDecKey` + - requires `--features impl_priority_queue` + - or `--features impl_all` This allows to use all the queue implementations interchangeably and pick the one fitting best to the use case. ### Performance & Benchmarks -*You may find the details of the benchmarks at [benches](https://github.com/orxfun/orx-priority-queue/blob/main/benches) folder.* +_You may find the details of the benchmarks at [benches](https://github.com/orxfun/orx-priority-queue/blob/main/benches) folder._ https://raw.githubusercontent.com/orxfun/orx-priority-queue/main/docs/bench_results.PNG The table above summarizes the benchmark results of basic operations on basic queues, and queues allowing decrease key operations. -* In the first benchmark, we repeatedly call `push` and `pop` operations on a queue while maintaining an average length of 100000: - * We observe that `BinaryHeap` (`DaryHeap<_, _, 2>`) performs almost the same as the standard binary heap. - * Experiments on different values of d shows that `QuaternaryHeap` (D=4) outperforms both binary heaps. - * Further increasing D to 8 does not improve performance. - * Finally, we repeat the experiments with `BinaryHeap` and `QuaternaryHeap` using the specialized [`push_then_pop`](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueue.html#tymethod.push_then_pop) operation. Note that this operation further doubles the performance, and hence, should be used whenever it fits the use case. -* In the second benchmark, we add [`decrease_key_or_push`](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueueDecKey.html#method.decrease_key_or_push) calls to the operations. Standard binary heap is excluded since it cannot implement `PriorityQueueDecKey`. - * We observe that `DaryHeapOfIndices` significantly outperforms other decrease key queues. - * Among `BinaryHeapOfIndices` and `QuaternaryHeapOfIndices`, the latter with D=4 again performs better. - +- In the first benchmark, we repeatedly call `push` and `pop` operations on a queue while maintaining an average length of 100000: + - We observe that `BinaryHeap` (`DaryHeap<_, _, 2>`) performs almost the same as the standard binary heap. + - Experiments on different values of d shows that `QuaternaryHeap` (D=4) outperforms both binary heaps. + - Further increasing D to 8 does not improve performance. + - Finally, we repeat the experiments with `BinaryHeap` and `QuaternaryHeap` using the specialized [`push_then_pop`](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueue.html#tymethod.push_then_pop) operation. Note that this operation further doubles the performance, and hence, should be used whenever it fits the use case. +- In the second benchmark, we add [`decrease_key_or_push`](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueueDecKey.html#method.decrease_key_or_push) calls to the operations. Standard binary heap is excluded since it cannot implement `PriorityQueueDecKey`. + - We observe that `DaryHeapOfIndices` significantly outperforms other decrease key queues. + - Among `BinaryHeapOfIndices` and `QuaternaryHeapOfIndices`, the latter with D=4 again performs better. ## C. Examples @@ -175,8 +176,8 @@ test_priority_queue_deckey(QuaternaryHeapWithMap::default()); You may see below two implementations of the Dijkstra's shortest path algorithm: one using a `PriorityQueue` and the other with a `PriorityQueueDecKey`. Please note the following: -* Priority queue traits allow us to be generic over queues. Therefore, we are able to implement the algorithm once that works for any queue implementation. -* The second implementation with a decrease key queue pushes some of the bookkeeping to the queue, and arguably leads to a cleaner algorithm implementation. +- Priority queue traits allow us to be generic over queues. Therefore, we are able to implement the algorithm once that works for any queue implementation. +- The second implementation with a decrease key queue pushes some of the bookkeeping to the queue, and arguably leads to a cleaner algorithm implementation. ```rust use orx_priority_queue::*; From efb7744a05d0baea1d84bd61562d4a320dded1e6 Mon Sep 17 00:00:00 2001 From: Ugur Arikan Date: Wed, 19 Nov 2025 18:37:48 +0100 Subject: [PATCH 2/6] Add '1.88' to toolchain matrix in CI workflow --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 806d114..1c5bfb4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,7 +15,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - toolchain: ["stable"] + toolchain: ["stable", "1.88"] steps: - uses: actions/checkout@v4 From 1c02009f72d5251625c6dadbcd8bd599b57450cf Mon Sep 17 00:00:00 2001 From: Ugur Arikan Date: Wed, 19 Nov 2025 18:39:53 +0100 Subject: [PATCH 3/6] Remove branch restrictions for CI workflow Removed main branch restriction for push and pull request events. --- .github/workflows/ci.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1c5bfb4..81fd82f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,7 @@ name: Rust on: push: - branches: [ "main" ] pull_request: - branches: [ "main" ] env: CARGO_TERM_COLOR: always From 6db5bec2a7713d7ef98e953c9e048392f8068d69 Mon Sep 17 00:00:00 2001 From: orxfun Date: Wed, 19 Nov 2025 18:47:38 +0100 Subject: [PATCH 4/6] revert rust version --- Cargo.toml | 2 -- README.md | 1 - 2 files changed, 3 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index ad8f229..8777148 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,7 +9,6 @@ license = "MIT OR Apache-2.0" repository = "https://github.com/orxfun/orx-priority-queue/" keywords = ["priority", "queue", "heap", "dary", "binary"] categories = ["algorithms", "data-structures", "mathematics", "no-std"] -rust-version = "1.88" [features] default = ["std"] @@ -20,7 +19,6 @@ impl_all = ["impl_priority_queue"] [dependencies] priority-queue = { version = "2.3", optional = true } - [[bench]] name = "basic_queue" harness = false diff --git a/README.md b/README.md index ae30b50..df68e73 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,6 @@ [![orx-priority-queue crate](https://img.shields.io/crates/v/orx-priority-queue.svg)](https://crates.io/crates/orx-priority-queue) [![orx-priority-queue crate](https://img.shields.io/crates/d/orx-priority-queue.svg)](https://crates.io/crates/orx-priority-queue) [![orx-priority-queue documentation](https://docs.rs/orx-priority-queue/badge.svg)](https://docs.rs/orx-priority-queue) -[![MSRV](https://img.shields.io/badge/MSRV-1.88.0-blue)](https://releases.rs/docs/1.88.0/) Priority queue traits and high performance d-ary heap implementations. From fcb12f30e2a7f808f59d9135ec081b9482501a08 Mon Sep 17 00:00:00 2001 From: Ugur Arikan Date: Wed, 19 Nov 2025 18:48:08 +0100 Subject: [PATCH 5/6] Update ci.yml --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 81fd82f..5f98c03 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - toolchain: ["stable", "1.88"] + toolchain: ["stable"] steps: - uses: actions/checkout@v4 From 062b1438e7e7da9c0d9b72dcfb870f8b8cf826f6 Mon Sep 17 00:00:00 2001 From: orxfun Date: Wed, 19 Nov 2025 18:58:40 +0100 Subject: [PATCH 6/6] increment version --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index 8777148..8955432 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "orx-priority-queue" -version = "1.7.0" +version = "1.8.0" edition = "2024" authors = ["orxfun "] readme = "README.md"