entropic::HandleTurnGuard Class Reference

gh#144 (v2.12.0): RAII turn claim + log scope, for the RUN paths. More...

#include </home/runner/work/entropic/entropic/src/facade/engine_handle.h>

Public Member Functions
	HandleTurnGuard (entropic_handle_t h, const char *session_key=nullptr)
	Enter the handle's log scope.
	~HandleTurnGuard ()
	Release the turn if this guard claimed it.
	HandleTurnGuard (const HandleTurnGuard &)=delete
HandleTurnGuard &	operator= (const HandleTurnGuard &)=delete
bool	claim ()
	Claim the turn.
const std::string &	key () const
	The session this guard claims for.
bool	claimed () const
	Whether this guard owns the turn.

Detailed Description

gh#144 (v2.12.0): RAII turn claim + log scope, for the RUN paths.

Sibling of HandleApiLock, and deliberately NOT built on it. HandleApiLock takes api_mutex; gh#109 removed that mutex from all six run entry points precisely so a long turn could not block entropic_interrupt() called from another thread. Reusing it here would silently re-break gh#109, which is the single mistake this refactor is most likely to make — hence a separate type rather than a subclass or a flag.

The claim is one compare-exchange on the engine's running_flag_. A second thread interrupting a 40-second turn still touches only atomics.

Usage at every run entry point:

HandleTurnGuard turn(handle, session_key);  // key optional; "" = default
if (!turn.claim()) { return ENTROPIC_ERROR_ALREADY_RUNNING; }

gh#158 (v2.13.0): the claim is scoped to a SESSION KEY. The keyed run entry points pass theirs; the unkeyed ones claim the default session, which is what they have always effectively done. Whether a second key may proceed concurrently is the engine's decision (concurrent_sessions), not the guard's — the guard only makes sure the key it claims is the key it releases.

Holding the claim across the WHOLE entry point — not just the engine call — is the point: the facade serialises results out of the same conversation the engine appends to, so releasing early would let a second thread mutate that vector mid-read. That is the race gh#144 reported.

@req REQ-API-009

Version

2.12.0

Definition at line 443 of file engine_handle.h.

Constructor & Destructor Documentation

HandleTurnGuard()

entropic::HandleTurnGuard::HandleTurnGuard ( entropic_handle_t  h, const char *  session_key = nullptr  )

inlineexplicit

Enter the handle's log scope.

Does NOT claim the turn.

Construction is deliberately side-effect-free beyond logging so the guard can be declared ahead of argument validation; claim() is then evaluated last in the precondition chain. A call that is going to be rejected for a null argument must not momentarily claim the engine and bounce a legitimate concurrent caller.

Null-handle safe: log id 0 is the reserved "no handle scope" sentinel.

Parameters

h	Engine handle, possibly null.
session_key	Session this guard claims for (gh#158), and publishes to this thread for the call's duration (gh#166).

Version

2.13.0

Definition at line 461 of file engine_handle.h.

~HandleTurnGuard()

entropic::HandleTurnGuard::~HandleTurnGuard ( )

inline

Release the turn if this guard claimed it.

Version

2.13.0 [reviewed]

Definition at line 476 of file engine_handle.h.

Member Function Documentation

claim()

bool entropic::HandleTurnGuard::claim ( )

inline

Claim the turn.

Idempotent for one guard.

Returns

true when this guard now owns the turn; false when another turn is already in flight on this handle. @req REQ-API-009

Version

2.13.0

Definition at line 490 of file engine_handle.h.

claimed()

bool entropic::HandleTurnGuard::claimed ( ) const

inline

Whether this guard owns the turn.

@utility

Version

2.12.0

Definition at line 510 of file engine_handle.h.

key()

const std::string & entropic::HandleTurnGuard::key ( ) const

inline

The session this guard claims for.

Returns

Session key; "" for the default session. @utility

Version

2.13.0

Definition at line 503 of file engine_handle.h.

---

The documentation for this class was generated from the following file:

• facade/engine_handle.h