Expose evaluation limits, cancellation, and usage through public facades

Open
  • Is something wrong?
#1,823 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
c
Domain
api

Research direction

Start with the listed public headers and facade implementations, especially wirelog/wirelog-easy.c, wirelog/wirelog_advanced.c, and the error mapping in wirelog/extension_registry.c; then review the referenced prerequisite issues and public-header checks. Extend the facade APIs and tests in the named tests/ files, including standalone cases registered in tests/meson.build. Done means the acceptance checklist passes for both facades, typed and untyped evaluation, ABI checks, and applicable sanitizers.

Written by the indexing model from the issue text.

Description

enhancement track/api

Outcome

Installed-header consumers can configure evaluation work limits, request cancellation from a second thread, read consumed work/stop reason and retry with a larger allowance through both easy and advanced facades. Existing callers keep their behavior.

Parent: #1817. Hard prerequisites: #1819, #1820, #1821, #1822. Public enablement must not expose controls before the supported engine paths enforce them.

Verified starting point

At e8e977ec6ffcc0bcc0b0a4aae56bb842da34b389, wl_session_options_t is internal/uninstalled. Easy open has a size-versioned options prefix and lazy plan/session creation; advanced has ordinary and extension-snapshot constructors, with no public general options. Public evaluation errors flow through wl_facade_session_error_code() defined in wirelog/extension_registry.c; wirelog/api_facade.c is another caller. Existing enum values live in wirelog/wirelog.h.

Required implementation

  • Expose an opaque retained evaluation-control handle and create/retain/release/request-cancel, quiescent configuration/reset, and completed-attempt report operations. Use the foundation's one-attached-logical-session ownership and documented concurrency rules; concurrent cancel must operate on independently live control storage, not a possibly destroyed session.
  • Append optional control configuration to wirelog_easy_open_opts_t; preserve all legacy prefix sizes and _reserved validation. Claim the control's owner and retain the handle during open, including lazy creation; a second session's open fails immediately. Unwind failed-open references/ownership and pass the same owner identity to the eventual internal session without a second attachment. Constructor options storage may die immediately after open returns.
  • Add a size/versioned advanced options constructor composing worker/backend selection, control and extension snapshot. Keep existing constructor signatures/default behavior; delegate with NULL/default control. Do not expose internal options, backend structs or C atomics.
  • Make limit update/reset and report access usable from both facades, including after a bounded-out attempt while input mutation is pending-retry restricted. Public operations must clearly report active-attempt reconfiguration refusal.
  • Add distinct public budget-exhausted and cancelled errors without renumbering existing values; update error strings and wl_facade_session_error_code(). Preserve precedence relative to expression/OOM and cleanup errors, including typed snapshot wrappers. Do not label legacy execution failures as budget events.
  • Apply controls to every public evaluating STEP and SNAPSHOT entry point, typed or untyped. Existing legacy executor behavior remains unlimited unless separately opted in; shared error mapping must remain compatible.
  • Public names use wirelog_/WIRELOG_, exported prototypes use WIRELOG_API. If adding a shared installed wirelog/wirelog-evaluation.h, edit wirelog_public_headers in meson.build first, include it consistently, and update enforced public-surface manifests/docs. Internal helpers use wl_evaluation_control_*.

Paths

wirelog/wirelog.h, wirelog/wirelog-types.h, wirelog/wirelog-easy.h, wirelog/wirelog-easy.c, wirelog/wirelog-advanced.h, wirelog/wirelog_advanced.c, wirelog/wirelog-internal.h, wirelog/extension_registry.c, wirelog/api_facade.c, meson.build, wirelog/meson.build; public header/ABI checks as required.

Extend tests/test_wirelog_easy.c, tests/test_wirelog_advanced.c, tests/test_wirelog_public_api.c, tests/standalone/test_standalone_wirelog_easy.c, tests/standalone/test_standalone_wirelog_advanced.c; register any new standalone/control cases in tests/meson.build.

Acceptance

  • Installed-header-only C and C++ consumers demonstrate configure → evaluate → read stats → raise limit/reset token → retry, for both facades.
  • Easy eager/lazy paths and advanced creation with/without extension snapshot retain the control correctly; caller releases its own reference after open without invalidating evaluation.
  • Old option prefixes, NULL options, current macros and old constructors give the same results/statuses as the reference with controls absent.
  • New option prefix truncation, unknown version, invalid reserved data, constructor/build failure and active reset refusal have defined tested outcomes.
  • Cross-thread cancel and budget exhaustion remain distinguishable from execution and memory failures through every supported typed/untyped evaluation wrapper and wirelog_error_string().
  • Completed reports survive failure and are available before retry. Successful retry emits the original-baseline delta once and allows normal session reuse.
  • Public facade/standalone tests, full ABI suite (prefix/export macro/header surface/testhook gates) and applicable ASan/UBSan checks pass.

Non-goals

No environment variable, deadline API, implicit process signal handler, exported internal session_options, or general concurrent session mutation contract. This issue exposes the completed mechanism; #1824 records parent-level conformance and final documentation evidence.

Dominant language
C
Stars
18
Forks
2
Avg merge
9h 44m
Merged PRs (30d)
162

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from semantic-reasoning/wirelog

All issues in semantic-reasoning/wirelog

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.