{"id":16411145,"url":"https://github.com/phoe/damn-fast-priority-queue","last_synced_at":"2025-10-08T16:04:45.756Z","repository":{"id":45495589,"uuid":"313285543","full_name":"phoe/damn-fast-priority-queue","owner":"phoe","description":"A heap-based priority queue whose first and foremost priority is speed.","archived":false,"fork":false,"pushed_at":"2024-07-01T07:08:11.000Z","size":44,"stargazers_count":34,"open_issues_count":4,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-06T03:24:01.106Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phoe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-16T11:49:33.000Z","updated_at":"2024-07-01T07:08:14.000Z","dependencies_parsed_at":"2024-11-10T00:44:28.697Z","dependency_job_id":"aa7e5314-13cf-497e-a0bc-992f68d9c0a8","html_url":"https://github.com/phoe/damn-fast-priority-queue","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoe%2Fdamn-fast-priority-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoe%2Fdamn-fast-priority-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoe%2Fdamn-fast-priority-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoe%2Fdamn-fast-priority-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phoe","download_url":"https://codeload.github.com/phoe/damn-fast-priority-queue/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240416345,"owners_count":19797796,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T06:44:41.321Z","updated_at":"2025-10-08T16:04:40.722Z","avatar_url":"https://github.com/phoe.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Damn Fast Priority Queue\n\nA heap-based priority queue whose first and foremost priority is [**speed**](https://www.youtube.com/watch?v=AkagvXwDsYU). Optionally comes in a stable flavor.\n\nBlame [@mfiano](https://github.com/mfiano/) for the existence of this library. He's the one who wanted a priority queue that's going to run as fast as possible in one of the hottest loops of his game engine ~~and then figured out that hey, he actually doesn't need a prio queue there~~.\n\n## License\n\nMIT.\n\n## Systems\n\n* This repository contains two systems:\n  * `damn-fast-priority-queue`, a faster but unstable priority queue (elements with the same priority are dequeued in unspecified order),\n  * `damn-fast-stable-priority-queue`, a fast and stable priority queue (elements with the same priority are dequeued in FIFO order).\n* The queues have identical APIs.\n  * These APIs are not generic, i.e. operators for one queue type must not be used on a queue instance of the other type.\n\n## Description\n\n* The queue enqueues objects along with their priorities.\n  * The stored objects may be of arbitrary type.\n  * The objects' priorities must be of type `(unsigned-byte 32)`.\n* The queue is a minimum queue (i.e. smallest priorities are dequeued first).\n* The queue is unbounded by default.\n  * The queue's storage automatically expands (which reallocates the queue storage).\n  * The queue's storage can be manually trimmed (which reallocates the queue storage).\n  * The queue can instead be configured to signal an error upon reaching its size limit.\n* The queue is **not** thread-safe.\n* The queue is **not** reentrant.\n\n## Implementation details\n\n* The queue internally uses two simple vectors: one for data, specialized on `t`, and another for priorities, specialized on `(unsigned-byte 32)`.\n  * The stable queue also uses a third simple vector for storing element insertion order, specialized on `(unsigned-byte 32)`.\n* The queue's storage has its initial storage size set to `256`. This value is customizable in the constructor.\n* Each time the queue runs out of storage, the storage is reallocated via `adjust-array` and its size is expanded by the `extension-factor` value provided at queue instantiation.\n* We assume that using simple vectors, calling `adjust-array` on them, and manually setting queue slots to the new vectors is faster than using adjustable vectors.\n\n## Optimization settings\n\n* The code uses structure classes in favor of standard classes.\n* The code uses standard, `inline`-proclaimed functions in favor of generic functions.\n* All functions are optimized for maximum `speed`.\n* By default, the code retains the default values of `debug`, `safety`, `space`, and `compilation-speed` optimize qualities. To set them all to 0, pray to your favorite deity and push a feature into `*features*` before compiling the respective system.\n  * for `damn-fast-priority-queue`, push `:real-damn-fast-priority-queue`,\n  * for `damn-fast-stable-priority-queue`, push `:real-damn-fast-stable-priority-queue`.\n\n## Exports\n\nAll exported functions are proclaimed `inline` by default.\n\n* **Classes**\n  * `queue` - names the priority queue structure class.\n* **Functions**\n  * `(make-queue \u0026optional initial-storage-size extension-factor extend-queue-p)` - make a priority queue.\n    * The initial storage size must be a non-negative integer. Its default value is `256`.\n    * The extension factor value must be a positive integer between `2` and `256`. Its default value is `2`.\n    * The queue can be configured to signal an error of type `queue-size-limit-reached` when its size is reached, instead of extending its storage. It is possible to retrieve the queue via the `queue-size-limit-reached-queue` reader and the object that was attempted to be stored via `queue-size-limit-reached-object`.\n  * `(copy-queue queue)` - makes a deep copy of the provided queue (including its storage vectors).\n  * `(enqueue queue object priority)` - enqueue an object.\n  * `(dequeue queue)` - dequeue an object.\n    * Secondary return value is true if the object was found and false if the queue was empty.\n  * `(peek queue)` - peek at an object that is first to be dequeued.\n    * Secondary return value is true if the object was found and false if the queue was empty.\n  * `(size queue)` - get the current element count of the queue.\n  * `(trim queue)` - trim the queue's storage by calling `adjust-array` on it with the current queue size.\n  * `(map queue function)` - calls the function on each element of `queue` in unspecified order and returns `nil`.\n* **Macros**\n  * `(do-queue (object queue \u0026optional result) \u0026body body)` - evaluates `body` with `object` bound to each element of `queue` in unspecified order and returns `result`.\n\n## Tests\n\n* For `damn-fast-priority-queue`:\n  * Non-verbose test: `(asdf:test-system :damn-fast-priority-queue)`\n  * Verbose test: `(damn-fast-priority-queue/test:run t)`\n* For `damn-fast-stable-priority-queue`:\n  * Non-verbose test: `(asdf:test-system :damn-fast-stable-priority-queue)`\n  * Verbose test: `(damn-fast-stable-priority-queue/test:run t)`\n\n## Performance tests\n\nSee [the Priority Queue Benchmark README](priority-queue-benchmark/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphoe%2Fdamn-fast-priority-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphoe%2Fdamn-fast-priority-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphoe%2Fdamn-fast-priority-queue/lists"}