Pr/timer

.github/actions/resolve-capy/action.yml

@@ -0,0 +1,63 @@
+#
+# Copyright (c) 2026 Steve Gerbino
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+# Official repository: https://github.com/cppalliance/corosio/
+#
+
+name: Resolve Capy branch
+description: >-
+  Resolve the capy repository and branch matching this build. Use the
+  capy branch with the same name as this build's branch (for pull
+  requests: the source branch, then the target branch). Inside a fork
+  the owner's capy fork is preferred, so fork branches build against
+  their matching capy fork branch. Cross-repo PRs into cppalliance
+  resolve against cppalliance/capy as before. Fall back to capy's
+  default branch.
+
+outputs:
+  repo:
+    description: The resolved capy repository (owner/capy).
+    value: ${{ steps.resolve.outputs.repo }}
+  ref:
+    description: The resolved capy branch.
+    value: ${{ steps.resolve.outputs.ref }}
+
+runs:
+  using: composite
+  steps:
+    - id: resolve
+      shell: bash
+      # Bind untrusted context values into env: head_ref is
+      # attacker-controlled on fork PRs, so never interpolate it into
+      # the script body.
+      env:
+        HEAD_REF: ${{ github.head_ref }}
+        BASE_REF: ${{ github.base_ref }}
+        REF_NAME: ${{ github.ref_name }}
+        OWNER: ${{ github.repository_owner }}
+      run: |
+        repo=cppalliance/capy
+        ref=
+        for candidate in "$HEAD_REF" "$BASE_REF" "$REF_NAME"; do
+          [ -n "$candidate" ] || continue
+          probed=
+          for fork in "$OWNER/capy" cppalliance/capy; do
+            # Skip a fork already probed for this candidate (the owner
+            # fork equals cppalliance/capy when running in cppalliance).
+            [ "$fork" = "$probed" ] && continue
+            probed="$fork"
+            if GIT_TERMINAL_PROMPT=0 git ls-remote --exit-code --heads "https://github.com/$fork.git" "$candidate" > /dev/null; then
+              repo="$fork"
+              ref="$candidate"
+              break 2
+            fi
+          done
+        done
+        if [ -z "$ref" ]; then
+          ref=$(GIT_TERMINAL_PROMPT=0 git ls-remote --symref "https://github.com/$repo.git" HEAD | awk '/^ref:/ { sub("refs/heads/", "", $2); print $2 }')
+        fi
+        echo "repo=$repo" >> "$GITHUB_OUTPUT"
+        echo "ref=$ref" >> "$GITHUB_OUTPUT"

.github/workflows/ci.yml

@@ -95,30 +95,14 @@ jobs:
             liburing-dev
             curl zip unzip tar pkg-config
 
-      # Use the capy branch with the same name as this build's branch
-      # (for pull requests: the source branch, then the target branch);
-      # fall back to capy's default branch.
       - name: Resolve Capy branch
         id: capy-ref
-        shell: bash
-        run: |
-          url=https://github.com/cppalliance/capy.git
-          ref=
-          for candidate in "${{ github.head_ref }}" "${{ github.base_ref }}" "${{ github.ref_name }}"; do
-            if [ -n "$candidate" ] && git ls-remote --exit-code --heads "$url" "$candidate" > /dev/null; then
-              ref="$candidate"
-              break
-            fi
-          done
-          if [ -z "$ref" ]; then
-            ref=$(git ls-remote --symref "$url" HEAD | awk '/^ref:/ { sub("refs/heads/", "", $2); print $2 }')
-          fi
-          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+        uses: ./corosio-root/.github/actions/resolve-capy
 
       - name: Clone Capy
         uses: actions/checkout@v4
         with:
-          repository: cppalliance/capy
+          repository: ${{ steps.capy-ref.outputs.repo }}
           ref: ${{ steps.capy-ref.outputs.ref }}
           path: capy-root
 
@@ -799,30 +783,14 @@ jobs:
         with:
           path: corosio-root
 
-      # Use the capy branch with the same name as this build's branch
-      # (for pull requests: the source branch, then the target branch);
-      # fall back to capy's default branch.
       - name: Resolve Capy branch
         id: capy-ref
-        shell: bash
-        run: |
-          url=https://github.com/cppalliance/capy.git
-          ref=
-          for candidate in "${{ github.head_ref }}" "${{ github.base_ref }}" "${{ github.ref_name }}"; do
-            if [ -n "$candidate" ] && git ls-remote --exit-code --heads "$url" "$candidate" > /dev/null; then
-              ref="$candidate"
-              break
-            fi
-          done
-          if [ -z "$ref" ]; then
-            ref=$(git ls-remote --symref "$url" HEAD | awk '/^ref:/ { sub("refs/heads/", "", $2); print $2 }')
-          fi
-          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+        uses: ./corosio-root/.github/actions/resolve-capy
 
       - name: Clone Capy
         uses: actions/checkout@v4
         with:
-          repository: cppalliance/capy
+          repository: ${{ steps.capy-ref.outputs.repo }}
           ref: ${{ steps.capy-ref.outputs.ref }}
           path: capy-root
 

.github/workflows/code-coverage.yml

@@ -150,30 +150,14 @@ jobs:
           echo "CMAKE_WOLFSSL_INCLUDE=${vcpkg_installed}/include" >> $GITHUB_ENV
           echo "CMAKE_WOLFSSL_LIBRARY=${vcpkg_installed}/lib/libwolfssl.a" >> $GITHUB_ENV
 
-      # Use the capy branch with the same name as this build's branch
-      # (for pull requests: the source branch, then the target branch);
-      # fall back to capy's default branch.
       - name: Resolve Capy branch
         id: capy-ref
-        shell: bash
-        run: |
-          url=https://github.com/cppalliance/capy.git
-          ref=
-          for candidate in "${{ github.head_ref }}" "${{ github.base_ref }}" "${{ github.ref_name }}"; do
-            if [ -n "$candidate" ] && git ls-remote --exit-code --heads "$url" "$candidate" > /dev/null; then
-              ref="$candidate"
-              break
-            fi
-          done
-          if [ -z "$ref" ]; then
-            ref=$(git ls-remote --symref "$url" HEAD | awk '/^ref:/ { sub("refs/heads/", "", $2); print $2 }')
-          fi
-          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+        uses: ./corosio-root/.github/actions/resolve-capy
 
       - name: Clone Capy
         uses: actions/checkout@v6
         with:
-          repository: cppalliance/capy
+          repository: ${{ steps.capy-ref.outputs.repo }}
           ref: ${{ steps.capy-ref.outputs.ref }}
           path: capy-root
 
@@ -391,30 +375,14 @@ jobs:
           echo "CMAKE_WOLFSSL_LIBRARY=${vcpkg_installed}/lib/libwolfssl.a" >> $GITHUB_ENV
           echo "CMAKE_OPENSSL_ROOT=C:/msys64/mingw64" >> $GITHUB_ENV
 
-      # Use the capy branch with the same name as this build's branch
-      # (for pull requests: the source branch, then the target branch);
-      # fall back to capy's default branch.
       - name: Resolve Capy branch
         id: capy-ref
-        shell: bash
-        run: |
-          url=https://github.com/cppalliance/capy.git
-          ref=
-          for candidate in "${{ github.head_ref }}" "${{ github.base_ref }}" "${{ github.ref_name }}"; do
-            if [ -n "$candidate" ] && git ls-remote --exit-code --heads "$url" "$candidate" > /dev/null; then
-              ref="$candidate"
-              break
-            fi
-          done
-          if [ -z "$ref" ]; then
-            ref=$(git ls-remote --symref "$url" HEAD | awk '/^ref:/ { sub("refs/heads/", "", $2); print $2 }')
-          fi
-          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+        uses: ./corosio-root/.github/actions/resolve-capy
 
       - name: Clone Capy
         uses: actions/checkout@v6
         with:
-          repository: cppalliance/capy
+          repository: ${{ steps.capy-ref.outputs.repo }}
           ref: ${{ steps.capy-ref.outputs.ref }}
           path: capy-root
 

.github/workflows/docs.yml

@@ -42,30 +42,14 @@ jobs:
         with:
           path: corosio-root
 
-      # Use the capy branch with the same name as this build's branch
-      # (for pull requests: the source branch, then the target branch);
-      # fall back to capy's default branch.
       - name: Resolve Capy branch
         id: capy-ref
-        shell: bash
-        run: |
-          url=https://github.com/cppalliance/capy.git
-          ref=
-          for candidate in "${{ github.head_ref }}" "${{ github.base_ref }}" "${{ github.ref_name }}"; do
-            if [ -n "$candidate" ] && git ls-remote --exit-code --heads "$url" "$candidate" > /dev/null; then
-              ref="$candidate"
-              break
-            fi
-          done
-          if [ -z "$ref" ]; then
-            ref=$(git ls-remote --symref "$url" HEAD | awk '/^ref:/ { sub("refs/heads/", "", $2); print $2 }')
-          fi
-          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+        uses: ./corosio-root/.github/actions/resolve-capy
 
       - name: Clone Capy
         uses: actions/checkout@v4
         with:
-          repository: cppalliance/capy
+          repository: ${{ steps.capy-ref.outputs.repo }}
           ref: ${{ steps.capy-ref.outputs.ref }}
           path: capy-root
 

doc/design/physical-structure.md

@@ -157,7 +157,6 @@ private:
 | io_read_file    | io_object                       | read_at(offset, buffers)                   |
 | io_write_file   | io_object                       | write_at(offset, buffers)                  |
 | io_file         | io_read_file, io_write_file     | read_at, write_at (diamond)                |
-| io_timer        | io_object                       | wait(duration), cancel()                   |
 | io_signal_set   | io_object                       | add(signal), wait(), cancel()              |
 | io_file_watch   | io_object                       | watch(path), wait() yielding change events |
 
@@ -306,7 +305,7 @@ private:
 | Type        | Base(s)       | Key Operations                                              |
 | ----------- | ------------- | ----------------------------------------------------------- |
 | process     | io_object     | spawn(), wait_for_exit(); stdin/stdout/stderr are pipe ends |
-| timer       | io_timer      | expires_after(), expires_at(), wait(), cancel()             |
+| delay/timeout | (free functions) | delay(duration/time_point), timeout(op, duration/time_point) |
 | signal_set  | io_signal_set | add(int), remove(int), wait(), cancel()                     |
 | serial_port | io_stream     | Baud rate, parity, flow control options                     |
 | file_watch  | io_file_watch | watch(path), wait() yields change events                    |
@@ -328,7 +327,7 @@ private:
 | Source location     | `src/corosio/src/{class}.cpp` (e.g. `tcp_socket.cpp`)                        |
 | Test files          | `test/unit/{class}.cpp` (e.g. `tcp_socket.cpp`)                              |
 | Platform OS headers | NEVER included at this layer                                                 |
-| Naming convention   | Protocol name, no prefix (e.g. `tcp_socket`, `tcp_acceptor`, `timer`)        |
+| Naming convention   | Protocol name, no prefix (e.g. `tcp_socket`, `tcp_acceptor`, `udp_socket`)   |
 | Member functions    | Inherited from abstract layer + protocol-specific operations                 |
 | Endpoint types      | Protocol-specific (e.g. `corosio::endpoint` for TCP/IP); lives at this layer |
 | Service interface   | `detail::socket_service`, `detail::acceptor_service` etc. in `src/detail/`   |
@@ -404,7 +403,6 @@ private:
 | ------------------------------ | ---------------------------- | ---------------------------- |
 | `native_tcp_socket<Backend>`   | tcp_socket                   | Awaitables inline impl logic |
 | `native_tcp_acceptor<Backend>` | tcp_acceptor                 | Awaitables inline impl logic |
-| `native_timer<Backend>`        | timer                        | Awaitables inline impl logic |
 | `native_signal_set<Backend>`   | signal_set                   | Awaitables inline impl logic |
 | (aliases)                      |                              |                              |
 | epoll_tcp_socket               | = `native_tcp_socket<epoll>` |                              |

doc/modules/ROOT/nav.adoc

@@ -28,7 +28,7 @@
 ** xref:4.guide/4e.tcp-acceptor.adoc[Acceptors]
 ** xref:4.guide/4f.endpoints.adoc[Endpoints]
 ** xref:4.guide/4g.composed-operations.adoc[Composed Operations]
-** xref:4.guide/4h.timers.adoc[Timers]
+** xref:4.guide/4h.timers.adoc[Delays and Timeouts]
 ** xref:4.guide/4i.signals.adoc[Signal Handling]
 ** xref:4.guide/4j.resolver.adoc[Name Resolution]
 ** xref:4.guide/4k.tcp-server.adoc[TCP Server]