Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
name: Docs

# PRs build only, to catch broken references before they reach main.
# Pushes to main, and manual runs on main, build and deploy.
on:
push:
branches: [main]
paths:
- docs/**
- VERSION
- .github/workflows/docs.yml
pull_request:
paths:
- docs/**
- VERSION
- .github/workflows/docs.yml
workflow_dispatch:

permissions:
contents: read

concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
name: "Docs: Build"
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@v6
with:
# this job executes repo-controlled python (conf.py and any sphinx
# extension it loads), so don't leave the token in .git/config
persist-credentials: false

- name: Install uv
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
enable-cache: true
cache-dependency-glob: docs/uv.lock

# --locked fails if docs/uv.lock is out of date with docs/pyproject.toml.
# -W turns Sphinx warnings into errors, so a broken reference fails here.
- name: Build docs
working-directory: docs
run: uv run --locked sphinx-build -W --keep-going -b html . _build/html

# allowlist the trusted triggers
- name: Upload artifact
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
uses: actions/upload-pages-artifact@v3
with:
path: docs/_build/html

deploy:
name: "Docs: Deploy"
needs: build
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

where is this gonna push? What's the url?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(hyprwm.github.io btw. Feel free to suggest changes)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that was my question, the domain. Taking up hyprwm.github.io is kinda yikes. Can't we do /hyprutils?

steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,8 @@ cmake_install.cmake
compile_commands.json
hyprutils.pc
.envrc

# docs
!docs/Makefile
docs/_build/
docs/.venv/
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@

Hyprutils is a small C++ library for utilities used across the Hypr* ecosystem.

## Documentation

API documentation is published at <https://hyprwm.github.io/hyprutils/>, and its
source lives in [docs/](docs/). To build it locally:

```sh
make -C docs html # output in docs/_build/html
make -C docs live # live-reloading server on 127.0.0.1:8000
```

Python dependencies are handled by [uv](https://docs.astral.sh/uv/); no manual
virtualenv setup is needed.

## Stability

Hyprutils depends on the ABI stability of the stdlib implementation of your compiler. Sover bumps will be done only for hyprutils ABI breaks, not stdlib.
Expand Down
23 changes: 23 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Minimal makefile for Sphinx documentation.
# Python dependencies are managed with uv (see pyproject.toml); `uv run`
# discovers this directory's project and creates/syncs the venv on demand.

UV ?= uv
SPHINXOPTS ?= -W --keep-going
SPHINXBUILD ?= $(UV) run sphinx-build
SOURCEDIR = .
BUILDDIR = _build

.PHONY: help live Makefile

help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

# Live-reloading dev server on http://127.0.0.1:8000
live:
@$(UV) run --group dev sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" \
--ignore "$(BUILDDIR)/*" $(SPHINXOPTS) $(O)

# Catch-all: route everything else to sphinx-build ("make html", "make clean", ...)
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
53 changes: 53 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Configuration file for the Sphinx documentation builder.
# https://www.sphinx-doc.org/en/master/usage/configuration.html

from pathlib import Path

# -- Project information -----------------------------------------------------

project = "hyprutils"
author = "hyprwm"
copyright = "hyprwm"

# Keep the docs in sync with the VERSION file at the repository root.
_version_file = Path(__file__).resolve().parent.parent / "VERSION"
release = _version_file.read_text().strip() if _version_file.is_file() else "unknown"
# MAJOR.MINOR convention
version = ".".join(release.split(".")[:2])

# -- General configuration ---------------------------------------------------

extensions = [
"myst_parser",
"sphinx_copybutton",
"sphinx_design",
]

exclude_patterns = ["_build", ".venv", "Thumbs.db", ".DS_Store"]

# deflist: term/definition lists. colon_fence: ::: directives, which can wrap
# ``` code fences without counting backticks.
myst_enable_extensions = ["deflist", "colon_fence"]

# Everything here is C++, so default to it for code fences and inline roles.
primary_domain = "cpp"
highlight_language = "cpp"

cpp_index_common_prefix = ["Hyprutils::Signal::", "Hyprutils::"]

# -- Options for HTML output -------------------------------------------------

html_theme = "furo"
html_title = f"hyprutils {release}"

html_theme_options = {
"source_repository": "https://github.com/hyprwm/hyprutils/",
"source_branch": "main",
"source_directory": "docs/",
}

# -- Options for sphinx-copybutton -------------------------------------------

# Strip shell prompts so copying a `$ cmd` block yields just `cmd`.
copybutton_prompt_text = r"\$ "
copybutton_prompt_is_regexp = True
40 changes: 40 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# hyprutils

Hyprutils is a small C++ library of utilities used across the Hypr\* ecosystem.
Public headers live under `include/hyprutils/`, and everything is installed as a
single shared library, `libhyprutils`.

This documentation is a work in progress. The signal system is documented first;
the remaining modules (`animation`, `cli`, `i18n`, `math`, `memory`, `os`,
`path`, `string`, `utils`) will follow.

```{toctree}
:maxdepth: 2
:caption: Modules

signal/index
```

## Conventions

* Every public header lives under `include/hyprutils/<module>/`, and its symbols
live in the matching `Hyprutils::<Module>` namespace.
* Types are prefixed by kind: `C` for classes, `I` for interfaces, `S` for plain
structs, `e` for enums.
* Examples assume the relevant `using namespace` unless the qualification
matters to the point being made.

## Building the documentation

Python dependencies are managed with [uv](https://docs.astral.sh/uv/) and
declared in `docs/pyproject.toml`. No manual venv setup is needed, as `uv run`
creates and syncs one on demand.

```sh
$ make -C docs html # output in docs/_build/html
$ make -C docs live # live-reloading server on 127.0.0.1:8000
$ make -C docs clean
```

Both targets pass `-W --keep-going`, so warnings are errors. Keep new pages
warning-free, since CI builds with the same flags.
19 changes: 19 additions & 0 deletions docs/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
[project]
name = "hyprutils-docs"
version = "0"
description = "Sphinx documentation for hyprutils"
requires-python = ">=3.11"
dependencies = [
"sphinx>=8.1",
"furo>=2024.8.6",
"sphinx-copybutton>=0.5.2",
"sphinx-design>=0.6.1",
"myst-parser>=4.0",
]

[dependency-groups]
dev = ["sphinx-autobuild>=2024.10.3"]

[tool.uv]
# The docs are not a Python package, just an environment to build them in.
package = false
144 changes: 144 additions & 0 deletions docs/signal/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# Signal

```cpp
#include <hyprutils/signal/Signal.hpp>
#include <hyprutils/signal/Listener.hpp>

using namespace Hyprutils::Signal;
```

```{cpp:namespace} Hyprutils::Signal
```

The signal module implements a synchronous, single-threaded observer pattern. An
object exposes one {cpp:class}`CSignalT` per event it can produce, and interested
parties subscribe to it. Emitting calls every registered handler inline, in
registration order, and returns once they have all run. There is no queue, no
dispatch thread, and no allocation per emission.
Comment on lines +15 to +17

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove the no-allocation emission guarantee

This guarantee is inaccurate for any signal with live listeners: CSignalBase::emitInternal copies the static-listener vector and, for handle-owned listeners, constructs a temporary std::vector and calls reserve(m_vListeners.size()), so emitting can allocate on every call. Keeping this statement in the new public docs misleads performance-sensitive users into relying on an allocation-free emission path that the implementation does not provide.

Useful? React with 👍 / 👎.


The module has two halves:

{doc}`signals`
: {cpp:class}`CSignalT`, the emitter. It is a variadic template over the types
the event carries, so handler signatures are checked at compile time instead of
unpacking a `std::any` at runtime.

{doc}`listeners`
: {cpp:class}`CSignalListener`, always held through the
{cpp:type}`CHyprSignalListener` shared pointer. Ownership of that pointer *is*
the subscription: when the last strong reference goes away, the handler stops
being called.

## A minimal example

```cpp
CSignalT<> ready;
CSignalT<int> valueChanged;

// subscribe; keep the returned handle alive for as long as you want events
CHyprSignalListener onChange = valueChanged.listen([](int value) {
printf("value is now %d\n", value);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cmon printf in 2026? std::print xd

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's fine, who cares. It's a documentation on signals, not on the right way to print in 2026.

});

valueChanged.emit(42); // prints
onChange.reset(); // unsubscribe
valueChanged.emit(7); // nothing happens
```

## The ownership model

The signal holds a *weak* reference to each listener; the subscriber holds the
*strong* one. That inversion is the central design decision of the module, and it
has two consequences worth internalising up front.

**Discarding the result of {cpp:func}`CSignalT::listen` unsubscribes
immediately.** The temporary shared pointer dies at the end of the full
expression, taking the listener with it, and the handler never runs. `listen()`
is marked `[[nodiscard]]` for exactly this reason.

```cpp
signal.listen([] { /* never called */ }); // wrong, and warns
auto listener = signal.listen([] { /* ok */ }); // right
```

**Subscriptions are torn down by the subscriber's destructor, for free.** Store
the handle in the object whose lifetime should bound the subscription and there
is nothing to unregister by hand, no callback that can fire into a destroyed
object, and no disconnect API to forget.

## The idiomatic shape

Producers group their signals in an anonymous struct member, so the event set
reads as a unit and callers write `obj.m_events.something`:

```cpp
class CDevice {
public:
struct SButtonEvent {
uint32_t timeMs = 0;
uint32_t button = 0;
bool pressed = false;
};

struct {
CSignalT<SButtonEvent> button;
CSignalT<> frame;
CSignalT<> destroy;
} m_events;
};
```

Note that events carrying data almost always carry a *single payload struct*
rather than a list of loose parameters. Adding a field to the struct is source
compatible with every existing handler; adding a template parameter to the signal
is not.

Consumers mirror that with a struct of handles, named after the signals they are
bound to:

```cpp
class CDeviceWatcher {
public:
explicit CDeviceWatcher(CDevice& device) {
m_listeners.button = device.m_events.button.listen([this](const CDevice::SButtonEvent& event) {
onButton(event);
});
m_listeners.destroy = device.m_events.destroy.listen([this] { onDestroy(); });
}

// no destructor needed: m_listeners dies with *this, so the lambdas
// capturing `this` can never be invoked afterwards

private:
void onButton(const CDevice::SButtonEvent& event);
void onDestroy();

struct {
CHyprSignalListener button;
CHyprSignalListener destroy;
} m_listeners;
};
```

When the set of subscriptions is not known at compile time, a
`std::vector<CHyprSignalListener>` or a map keyed by name works the same way:
erasing the element unsubscribes. See {ref}`storing-listeners`.

The one place the ownership model does not apply is
{cpp:func}`CSignalT::listenStatic`, which hands the signal ownership of the
handler. See {ref}`static-listeners` for when that is the right call.

## Thread safety

There is none. Neither {cpp:class}`CSignalT` nor {cpp:class}`CSignalListener`
synchronises anything: the listener lists are plain vectors and the reference
counts behind {cpp:type}`CHyprSignalListener` are non-atomic. Register, emit, and
destroy on one thread. To cross a thread boundary, hand the event to your event
loop and emit from the loop's thread.

```{toctree}
:maxdepth: 2

signals
listeners
```
Loading
Loading