add bracket, reworked op and top-level perform

[lePereT]

What type of PR is this? (check all applicable)

• 🍕 Feature
• 📝 Documentation Update
• 🧑‍💻 Code Refactor
• ✅ Test

Description

Pushes fibers.op towards a first-class CML event API and rewires the library, examples, and tests around an explicit perform entry point.

Main changes:

• Core op API

  • Introduces op.perform(ev) as the single synchronization primitive, instead of calling :perform() on events.
  • Adds Event:or_else(fallback_thunk) as a biased choice combinator using a “next turn” primitive rather than the old perform_alt.
  • Adds Event:on_abort(f) and wires it into the same nack machinery as with_nack, so abort handlers fire when an arm loses in a choice.
  • Introduces op.bracket(acquire, release, use) for RAII-style resource protocols over events (release called on both success and abort).
  • Adds op.always(value) and op.never() helpers for simple always-ready / never-ready primitives.
  • Extends op.new_cond to support abort-only conds (optional abort_fn, no wait_op), and updates nack signalling logic to drive both with_nack and on_abort.

• Library & examples

  • Switches all internal call sites from ev:perform() / ev:perform_alt() to op.perform(ev) and ev:or_else(...).
  • Updates fibers.channel, fibers.cond, fibers.waitgroup, fibers.sleep, fibers.stream, fibers.stream.file, fibers.pollio, fibers.exec, fibers.alarm, and the cqueues integration example to import perform/choice locally and use the new API.
  • Adjusts README and basic examples (choices, choices-alt, choices-adv, context examples, lua-http integration) to show the choice(...) + perform(...) style instead of method-chaining on ops.

• Tests

  • Reworks tests/test_op.lua into a compact suite aligned with the new API:

    • Uses perform, choice, always, never, or_else, with_nack, and bracket.
    • Covers async paths, guards, nested with_nack, and bracket abort vs success semantics.

  • Updates tests/test_stream-file.lua, tests/test_waitgroup.lua, and tests/test_context.lua to:

    • Use perform/choice instead of :perform()/perform_alt().
    • Express non-blocking alternatives via :or_else(...) instead of perform_alt.

• Docs / formatting

  • README example updated to the new event style and some minor whitespace tidy-ups.

Behavioural note: this is a public API nudge — consumers should migrate from op.choice(...):perform[_alt]() to perform(choice(...)) / ev:or_else(...) over time.

This passes the full test suite.

Related Issues, Tickets & Documents

None.

Screenshots/Recordings

Not applicable.

Manual test

• 👍 yes

Manual test description

Ran the full test suite locally (including updated op / stream / waitgroup / context tests) and exercised the examples using the new perform/choice API.

Added tests?

• 👍 yes

Added to documentation?

• 📜 README.md

[optional] Are there any post-deployment tasks we need to perform?

• Downstream users calling :perform() / :perform_alt() on ops should be guided towards op.perform(ev) and ev:or_else(...).