{"id":15285855,"url":"https://github.com/hnc-agency/shq","last_synced_at":"2025-08-01T17:38:25.767Z","repository":{"id":57547945,"uuid":"443087345","full_name":"hnc-agency/shq","owner":"hnc-agency","description":"Shared inter-process queues","archived":false,"fork":false,"pushed_at":"2024-01-03T15:36:39.000Z","size":151,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-20T05:47:45.469Z","etag":null,"topics":["erlang","queues"],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hnc-agency.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,"zenodo":null}},"created_at":"2021-12-30T13:45:35.000Z","updated_at":"2025-07-05T00:05:39.000Z","dependencies_parsed_at":"2025-04-13T02:39:30.149Z","dependency_job_id":"184315d7-a0ca-4c5a-8fe1-4be0348ca192","html_url":"https://github.com/hnc-agency/shq","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/hnc-agency/shq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hnc-agency%2Fshq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hnc-agency%2Fshq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hnc-agency%2Fshq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hnc-agency%2Fshq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hnc-agency","download_url":"https://codeload.github.com/hnc-agency/shq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hnc-agency%2Fshq/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268269158,"owners_count":24223198,"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","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","queues"],"created_at":"2024-09-30T15:07:55.278Z","updated_at":"2025-08-01T17:38:25.741Z","avatar_url":"https://github.com/hnc-agency.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shq - Shared inter-process queues\n\n ![Tests](https://github.com/hnc-agency/shq/actions/workflows/ci.yml/badge.svg)\n :link: [Hex package](//hex.pm/packages/shq)\n\n`shq` requires OTP 24 or later.\n\n## Usage\n\n### Starting a queue\n\n```erlang\n%% Start a non-linked queue\n{ok, Pid} = shq:start(Opts).\n{ok, Pid} = shq:start(ServerName, Opts).\n\n%% Start a linked queue\n{ok, Pid} = shq:start_link(Opts).\n{ok, Pid} = shq:start_link(ServerName, Opts).\n\n%% Start a monitored queue\n{ok, {Pid, Mon}} = shq:start_monitor(Opts).\n{ok, {Pid, Mon}} = shq:start_monitor(ServerName, Opts).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerName\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eA server name as used when starting a named \u003ccode\u003egen_server\u003c/code\u003e.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003eOpts\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eA map or property list of options\n    \u003cdl\u003e\n      \u003cdt\u003e\u003ccode\u003emax =\u003e non_neg_integer() | infinity\u003c/code\u003e\u003c/dt\u003e\n      \u003cdd\u003eThe maximum number of items the queue can hold (default: \u003ccode\u003einfinity\u003c/code\u003e).\u003c/dd\u003e\n    \u003c/dl\u003e\n  \u003c/dd\u003e\n\u003c/dl\u003e\n\n### Inserting an item\n\n```erlang\n%% Insert an item at the rear\nshq:in(ServerRef, Item).\nshq:in(ServerRef, Item, Timeout).\n\n%% Insert an item at the front\nshq:in_r(ServerRef, Item).\nshq:in_r(ServerRef, Item, Timeout).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eA server reference as used with \u003ccode\u003egen_server\u003c/code\u003e.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003eItem\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eThe item to insert.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003eTimeout\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eA timeout to wait for a slot to become available if the queue is full (default: \u003ccode\u003e0\u003c/code\u003e).\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe return value is either the atom `ok` if the item was queued, the atom `full` if the queue was\nfull, or the atom `closed` if the queue was not accepting new items at the time of the call.\n\nWhen these functions return `full` or `closed`, it is guaranteed that the given item was not inserted,\nand will not be inserted later without calling this function again.\n\n### Retrieving an item\n\n```erlang\n%% Retrieving an item from the front\nshq:out(ServerRef).\nshq:out(ServerRef, Timeout).\n\n%% Retrieving an item from the rear\nshq:out_r(ServerRef).\nshq:out_r(ServerRef, Timeout).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eSee \"Inserting\".\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003eTimeout\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eA timeout to wait for an item to become available if the queue is empty (default: \u003ccode\u003e0\u003c/code\u003e).\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe return value is either a tuple `{ok, Item}`, or the atom `empty`.\n\nWhen these functions return `empty`, it is guaranteed that no item was removed from the queue, and\nnone will be removed later without calling this function again.\n\n### Peeking\n\n```erlang\n%% Peek at the front\nshq:peek(ServerRef).\n\n%% Peek at the rear\nshq:peek_r(ServerRef).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eSee \"Inserting\".\u003c/dd\u003e\n\u003c/dl\u003e\n\nPeeking is the same as retrieving, but without removing the item from the queue.\n\nThe operation will always return instantly, ie there is no way to wait for an item to become available\nif the queue is empty.\n\n### Draining a queue\n\n```erlang\n%% Draining a quee from the front\nshq:drain(ServerRef).\n\n%% Draining a queue from the rear\nshq:drain_r(ServerRef).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eSee \"Inserting\".\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe return value is a list of all items that were in the queue at the time when the call was made,\nincluding the ones that were waiting for insertion.\n\n### Retrieving queue size\n\n```erlang\nshq:size(ServerRef).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eSee \"Inserting\".\u003c/dd\u003e\n\u003c/dl\u003e\n\nRetrieves the number of items in the queue.\n\nThe return value is a non-negative integer.\n\n### Closing and Reopening a queue\n\n```erlang\n%% Closing a queue\nok=shq:close(ServerRef).\n\n%% Reopening a queue\nok=shq:open(ServerRef).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eSee \"Inserting\".\u003c/dd\u003e\n\u003c/dl\u003e\n\nWhen a queue is closed, all subsequent insert operations will be rejected and return `closed`\nuntil it is reopened.\n\nThe queue status can be queried via `shq:status(ServerRef)`.\n\n### Stopping a queue\n\n```erlang\nok=shq:stop(ServerRef).\n```\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003eServerRef\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eSee \"Inserting\".\u003c/dd\u003e\n\u003c/dl\u003e\n\nAll items left will be lost when a queue is stopped.\n\n\n## Notes\n\nAs `shq` queues are backed by `ets` tables of type `set`, the number of items in a queue does\nnot affect its performance. However, as `ets` tables live in memory, `shq` queues are not\nsuitable for storing vast numbers of large items. It is also noteworthy that items waiting to\nbe inserted into a queue that is currently full will still be stored in the backing table,\nalbeit temporarily, and thus still against available memory.\n\n\n## Authors\n\n* Maria Scott (Maria-12648430)\n* Jan Uhlig (juhlig)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhnc-agency%2Fshq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhnc-agency%2Fshq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhnc-agency%2Fshq/lists"}