contur::NativeEngine Class Reference

Native host-process execution engine. More...

#include <native_engine.h>

Inheritance diagram for contur::NativeEngine:

Public Member Functions
	NativeEngine (ITracer &tracer, std::uint32_t tickQuantumMs=5)
	Constructs a NativeEngine.
	~NativeEngine () override
	Destroys the engine and forcibly terminates any surviving children.
	NativeEngine (const NativeEngine &)=delete
NativeEngine &	operator= (const NativeEngine &)=delete
	NativeEngine (NativeEngine &&) noexcept
NativeEngine &	operator= (NativeEngine &&) noexcept
ExecutionResult	execute (ProcessImage &process, std::size_t tickBudget) override
	Executes the given process for up to tickBudget ticks.
void	halt (ProcessId pid) override
	Forcibly halts execution of the given process.
std::string_view	name () const noexcept override
	Returns the human-readable name of this engine.
std::string	capturedStdout (ProcessId pid) const
	Returns the captured stdout for a process, or an empty string when unknown / not yet drained. Useful for tests and demos.
bool	isTracking (ProcessId pid) const noexcept
	Returns true when the engine still tracks pid (process not yet reaped).
Public Member Functions inherited from contur::IExecutionEngine
virtual	~IExecutionEngine ()=default

Private Attributes
std::unique_ptr< Impl >	impl_

Additional Inherited Members
Protected Member Functions inherited from contur::IExecutionEngine
	IExecutionEngine ()=default
	IExecutionEngine (const IExecutionEngine &)=default
IExecutionEngine &	operator= (const IExecutionEngine &)=default
	IExecutionEngine (IExecutionEngine &&)=default
IExecutionEngine &	operator= (IExecutionEngine &&)=default

Detailed Description

Native host-process execution engine.

Reads ProcessImage::nativePath() on first dispatch for a given PID, spawns the host binary in a suspended state, and resumes / suspends the primary thread for each execute(...) burst. Stdout is captured via an anonymous pipe and surfaced through ITracer.

Behaviour summary:

• First execute() call: CreateProcessW (Windows) with a redirected stdout pipe and CREATE_SUSPENDED. Returns BudgetExhausted after running for the configured slice — even if the process completes immediately, the next execute() call detects exit and returns ProcessExited.
• Subsequent calls: ResumeThread → wait tickBudget * tickQuantumMs ms → SuspendThread. Drain stdout. Detect exit via WaitForSingleObject returning WAIT_OBJECT_0.
• halt(): marks the PID; the next execute() call (or an explicit external sweep) calls TerminateProcess and returns Halted.

NativeEngine is non-portable by design. On non-Windows hosts every method returns ExecutionResult::error(...). The class still compiles everywhere (the Win32 implementation is gated inside the .cpp).

Definition at line 47 of file native_engine.h.

Constructor & Destructor Documentation

NativeEngine() [1/3]

contur::NativeEngine::NativeEngine ( ITracer & tracer, std::uint32_t tickQuantumMs = 5 )

explicit

Constructs a NativeEngine.

Parameters

tracer	Reference to the simulator tracer (must outlive the engine).
tickQuantumMs	Wallclock milliseconds per simulation tick.

Referenced by NativeEngine(), NativeEngine(), operator=(), and operator=().

~NativeEngine()

contur::NativeEngine::~NativeEngine ( )

override

Destroys the engine and forcibly terminates any surviving children.

NativeEngine() [2/3]

contur::NativeEngine::NativeEngine ( const NativeEngine & )

delete

References NativeEngine().

NativeEngine() [3/3]

contur::NativeEngine::NativeEngine ( NativeEngine && )

noexcept

References NativeEngine().

Member Function Documentation

capturedStdout()

std::string contur::NativeEngine::capturedStdout ( ProcessId pid ) const

nodiscard

Returns the captured stdout for a process, or an empty string when unknown / not yet drained. Useful for tests and demos.

References capturedStdout().

Referenced by capturedStdout().

execute()

ExecutionResult contur::NativeEngine::execute ( ProcessImage & process, std::size_t tickBudget )

nodiscardoverridevirtual

Executes the given process for up to tickBudget ticks.

The engine runs the process until one of:

• The tick budget is exhausted (preemption)
• The process exits (Halt / Int Exit)
• An error or interrupt occurs that requires kernel attention

Parameters

process	The process image to execute (registers + code).
tickBudget	Maximum number of ticks (instructions) to execute.

Returns

An ExecutionResult describing the outcome.

Implements contur::IExecutionEngine.

References execute().

Referenced by execute().

halt()

void contur::NativeEngine::halt ( ProcessId pid )

overridevirtual

Forcibly halts execution of the given process.

Parameters

pid	The process ID to halt.

Implements contur::IExecutionEngine.

References halt().

Referenced by halt().

isTracking()

bool contur::NativeEngine::isTracking ( ProcessId pid ) const

nodiscardnoexcept

Returns true when the engine still tracks pid (process not yet reaped).

References isTracking().

Referenced by isTracking().

name()

std::string_view contur::NativeEngine::name ( ) const

nodiscardoverridevirtualnoexcept

Returns the human-readable name of this engine.

Returns

"Interpreter" or "Native", etc.

Implements contur::IExecutionEngine.

References name().

Referenced by name().

operator=() [1/2]

NativeEngine & contur::NativeEngine::operator= ( const NativeEngine & )

delete

References NativeEngine().

operator=() [2/2]

NativeEngine & contur::NativeEngine::operator= ( NativeEngine && )

noexcept

References NativeEngine().

Member Data Documentation

impl_

std::unique_ptr<Impl> contur::NativeEngine::impl_

private

Definition at line 82 of file native_engine.h.

---

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

• include/contur/execution/native_engine.h