npr::rf::IMacEngine class
#include <npr/mac/mac_engine.hpp>

Thin role-neutral MAC boundary used by NprRuntime.

The interface is intentionally small. Runtime owns orchestration, queues, and PHY execution. Role-specific MAC implementations own signaling policy, connection/admission logic, allocation handling, and per-role state.

Derived classes

class MasterMacEngine final
First PacketRF NPR master MAC implementation.
class SlaveMacEngine final
Main slave-side NPR MAC engine.

Constructors, destructors, conversion operators

~IMacEngine() defaulted virtual

Public functions

auto allocation_age_us(uint64_t now_us) const -> uint64_t pure virtual
Returns allocation age for diagnostics.
auto client_id() const -> uint8_t pure virtual
Returns current local client ID, if assigned by the active role.
auto connected() const -> bool pure virtual
Returns current link state for generic runtime/status consumers.
auto consume_ipv4_downlink_packet() -> bool pure virtual
Releases the front downlink IPv4 packet after successful handoff.
auto enqueue_ipv4_uplink_packet(const uint8_t* packet, size_t packet_size) -> bool pure virtual
Queues one host IPv4 packet for uplink.
auto init(const MacInitParams& params) -> bool pure virtual
Initializes engine with role-neutral runtime context.
void log_signaling_stats_periodic(uint64_t now_us) pure virtual
Emits periodic role-specific signaling diagnostics.
auto network_config_snapshot(NprNetworkConfig* out) const -> bool pure virtual
Copies current role-specific effective network config snapshot.
auto on_slot_burst_plan_result(const MacSlotBurstPlanResult& plan) -> MacSlotBurstPlanAction pure virtual
Classifies burst-planner output into runtime action.
auto on_slot_burst_tx_result(const MacSlotBurstTxFeedback& feedback) -> bool pure virtual
Applies PHY TX result to MAC state and returns whether burst should continue.
void on_tx_failure() pure virtual
Notifies MAC about failed frame transmission.
void on_tx_success(SlotTxFrameKind kind, uint64_t now_us) pure virtual
Notifies MAC about successful frame transmission.
void on_unslotted_tx_result(MacUnslottedAction action, bool sent, uint64_t now_us) pure virtual
Feeds unslotted transmission result back to MAC state.
auto peek_ipv4_downlink_packet(uint8_t* out, size_t out_capacity, size_t* out_size) const -> bool pure virtual
Copies the current front downlink IPv4 packet without releasing ownership.
auto plan_slot_burst_tx(const MacSlotBurstPlanInput& in, MacSlotBurstPlanResult* out) -> bool pure virtual
Plans one step of slotted burst utilization.
auto plan_unslotted_tx(uint64_t now_us, MacUnslottedAction action, MacUnslottedTxPlan* out) -> bool pure virtual
Emits role-specific unslotted signaling frame when needed.
auto process_received_packet(const uint8_t* packet, size_t packet_size, uint64_t packet_time_us, bool local_rssi_valid, uint8_t local_rssi, MacRxProcessResult* out) -> bool pure virtual
Processes one decoded-on-air packet and updates MAC state.
void reset(uint64_t now_us) pure virtual
Resets dynamic MAC state while keeping static configuration.
auto should_continue_slot_burst(uint32_t sent_in_slot, uint64_t now_us, const SlotTxTimeBudget& slot_budget) const -> bool pure virtual
Returns whether MAC policy allows another frame in current slot burst.
auto slot_budget_us() const -> uint32_t pure virtual
Returns current slot budget in microseconds.
auto sync_age_us(uint64_t now_us) const -> uint64_t pure virtual
Returns sync age for diagnostics.
void tick(const MacTickInput& input, MacTickPlan* out_plan) pure virtual
Computes one-step MAC execution plan for runtime.
auto who_cache_snapshot(SignalingWhoEntry* out_entries, size_t max_entries) const -> size_t pure virtual
Copies current role-neutral WHO/neighbor cache entries for external observers.

Function documentation

bool npr::rf::IMacEngine::network_config_snapshot(NprNetworkConfig* out) const pure virtual

Copies current role-specific effective network config snapshot.

Current slave MAC returns CONNECT_ACK-derived client assignment state. Engines that do not expose an equivalent snapshot may return false.

bool npr::rf::IMacEngine::peek_ipv4_downlink_packet(uint8_t* out, size_t out_capacity, size_t* out_size) const pure virtual

Copies the current front downlink IPv4 packet without releasing ownership.

Runtime uses this two-phase handoff to keep the packet in MAC-owned storage until the next queue boundary accepts it.

size_t npr::rf::IMacEngine::who_cache_snapshot(SignalingWhoEntry* out_entries, size_t max_entries) const pure virtual

Copies current role-neutral WHO/neighbor cache entries for external observers.

Both slave and master implementations should expose the same observability model here whenever practical.