{"id":15056405,"url":"https://github.com/silviucpp/epqueue","last_synced_at":"2025-08-20T12:32:27.158Z","repository":{"id":57495678,"uuid":"65082213","full_name":"silviucpp/epqueue","owner":"silviucpp","description":"A high performant Erlang NIF Priority Queue implemented using a binary heap","archived":false,"fork":false,"pushed_at":"2024-11-05T19:49:35.000Z","size":47,"stargazers_count":22,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-07T18:01:49.970Z","etag":null,"topics":["erlang","priority","queue"],"latest_commit_sha":null,"homepage":"","language":"Erlang","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/silviucpp.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}},"created_at":"2016-08-06T12:47:29.000Z","updated_at":"2024-11-05T19:49:23.000Z","dependencies_parsed_at":"2022-08-28T19:51:46.613Z","dependency_job_id":"3d46b69d-ba69-4842-aec2-8d466e8b94b0","html_url":"https://github.com/silviucpp/epqueue","commit_stats":{"total_commits":36,"total_committers":3,"mean_commits":12.0,"dds":"0.19444444444444442","last_synced_commit":"850ddf431ee11a2629c1af833053b4c89ba17f59"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Fepqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Fepqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Fepqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Fepqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/silviucpp","download_url":"https://codeload.github.com/silviucpp/epqueue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230423564,"owners_count":18223435,"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":["erlang","priority","queue"],"created_at":"2024-09-24T21:50:56.842Z","updated_at":"2024-12-19T11:13:15.031Z","avatar_url":"https://github.com/silviucpp.png","language":"Erlang","readme":"epqueue\n================\n\n[![Build Status](https://app.travis-ci.com/silviucpp/epqueue.svg?branch=master)](https://travis-ci.com/github/silviucpp/epqueue)\n[![GitHub](https://img.shields.io/github/license/silviucpp/epqueue)](https://github.com/silviucpp/epqueue/blob/master/LICENSE)\n[![Hex.pm](https://img.shields.io/hexpm/v/epqueue)](https://hex.pm/packages/epqueue)\n\nA high performant Erlang Priority Queue implemented using a binary heap (using NIF)\n\nConcurrency\n-----------\n\nThe queues provides support for concurrent access. You can specify the concurrent model using `{global_lock, true|false}` option (default is `false`).\n\nBased on `global_lock` option the queue behaves as follow:\n\n- `false` : The process that creates the queue is the only one that can operate on it. If any other process will try to access the queue will fail with a `badarg` exception\n- `true` : The returned queue reference can be stored and passed between processes on the same node. Also any process can operate with the queue (a mutex will be used for concurrency control)\n\nLifetime\n-----------\n\nLike any other data a queue reference returned using `epqueue:new` or an item reference returned using `epqueue:insert` are garbaged collected by Erlang VM when there is no longer any reference to them.\nThe references can be stored and passed between processes on the same node and also sored in a ETS table.\n\nQuick start\n-----------\n\nYou need to have at least Erlang OTP 19. This is because `enif_binary_to_term` and `enif_term_to_binary` are not available in previous versions.\nThis can be changed if it's required by moving the encoding/decoding or terms in Erlang and in NIF only store the received binary.\n\nCompile:\n\n```sh\nrebar compile\n```\n\nor\n\n```sh\nrebar3 compile\n```\n\nSimple usage:\n\n```erlang\n{ok, Q} = epqueue:new([]).\n{ok, _Ref} = epqueue:insert(Q, 1, 1).\n{ok, 1, 1} = epqueue:peek(Q).\n1 = epqueue:size(Q).\n{ok, 1, 1} = epqueue:pop(Q).\n0 = epqueue:size(Q).\n```\n\nAPI\n-----------\n\n- `epqueue:new(Opts)` - Create a new queue. As argument receives a list of settings. The only supported option right now is `{global_lock, true|false}`. For more details read the Concurrency section.\n- `insert(QueueRef, Data, Priority)` - Insert an element in the queue with a specified priority. In case of success returns `{ok, ItemRef}`. The reference can be used later in case you want to remove a specific element form the queue.  \n- `remove(QueueRef, Ref)` - Remove a specified element from the queue. `Ref` is the one returned by the `epqueue:insert/3` method.\n- `pop(QueueRef)` - Removes the element with the lowest priority from the queue (the head element). Returns `{ok, Data, Priority}` in case of success\n- `peek(QueueRef)` - Returns the element `{ok, Data, Priority}` with the lowest priority (the head element) without removing it.\n- `epqueue:size(QueueRef)` - Get the size of a queue.\n- `rank(QueueRef, Ref)` - Get the rank of a specified element from the queue. `Ref` is the one returned by the `epqueue:insert/3` method.\n\nTests\n------------\n\nIn order to run the integrity tests run `rebar3 eunit` from project root. \n\nPerformance testing\n-----------\n\nResults are generated on a MacBook Pro (Intel Core i7 4 cores at 2.5 GHz):\nThe `insert overhead` is the time spent to generate `ELEMENTS` random numbers for the priorities,\n\n- `make bench_serial` inserts a number of `ELEMENTS` with priorities from 0 to `MAX_PRIORITY` in a queue that\nuse or not a lock.\n\n```erl\nmake bench_serial ELEMENTS=1000000 MAX_PRIORITY=10000000 USE_LOCK=true\ninsert overhead: 252.764 ms insert time: 740.722 ms pop time: 1833.721 ms\n\nmake bench_serial ELEMENTS=1000000 MAX_PRIORITY=10000000 USE_LOCK=false\ninsert overhead: 250.178 ms insert time: 726.999 ms pop time: 1771.064 ms\n```\n\n- `bench_concurrent` spawn a number of `PROCS` processes that will insert a number of `ELEMENTS` with priorities \nfrom 0 to `MAX_PRIORITY` in a queue (lock is mandatory).\n\n```erl\nmake bench_concurrent PROCS=1 ELEMENTS=1000000 MAX_PRIORITY=10000000\ninsert overhead: 274.339 ms insert time: 778.185 ms pop time: 1772.712 ms\n\nmake bench_concurrent PROCS=2 ELEMENTS=1000000 MAX_PRIORITY=10000000\ninsert overhead: 139.748 ms insert time: 2408.561 ms pop time: 4563.286 ms \n\nmake bench_concurrent PROCS=3 ELEMENTS=1000000 MAX_PRIORITY=10000000\ninsert overhead: 100.252 ms insert time: 3528.367 ms pop time: 4913.981 ms \n\nmake bench_concurrent PROCS=4 ELEMENTS=1000000 MAX_PRIORITY=10000000\ninsert overhead: 77.775 ms insert time: 3603.385 ms pop time: 5055.776 ms \n\nmake bench_concurrent PROCS=20 ELEMENTS=1000000 MAX_PRIORITY=10000000\ninsert overhead: 76.704 ms insert time: 3676.474 ms pop time: 5039.594 ms \n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilviucpp%2Fepqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsilviucpp%2Fepqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilviucpp%2Fepqueue/lists"}