#include <GPSCommandChannel.h>

Public Member Functions
uint64_t	nowUs () const

GPSDeadline	operationDeadline () const

GPSDeadline	commandDeadline () const
	Deadline of the current command attempt, set by beginCommand().

GPSDeadlineScope	deadlineScope (std::chrono::milliseconds timeout)

GPSDeadlineScope	deadlineScope (GPSDeadline deadline)

bool	failed () const

GPSProtocolError	error () const

const QString &	errorDetail () const

void	setErrorDetail (const QString &detail)

void	failControl (GPSProtocolError failure=GPSProtocolError::Protocol)

void	failControl (const QString &detail)
	Records a protocol failure described by detail unless a failure is already recorded, whose detail stays.

void	failSequence (const GPSCommandSequence::Result &result)

void	failNoAnswer (std::span< const unsigned > rates)

GPSCommandOutcome	failureOutcome () const
	The command outcome that reports the sticky failure; Pending while healthy.

void	beginCommand (GPSConfigurationStep step)

GPSConfigurationEvidence	completeCommand (GPSCommandOutcome outcome)
	Retires the current attempt and reports it; repeated completion returns the retained evidence unchanged.

void	finishCommand (GPSCommandOutcome outcome)

const GPSConfigurationEvidence &	currentCommand () const

int	read (std::span< uint8_t > buffer, std::chrono::milliseconds timeout)
	Reads raw bytes without decoding them.

bool	write (QByteArrayView bytes)

bool	setBaudrate (unsigned baudrate)

void	wait (std::chrono::microseconds duration)
	Waits for duration, capped by the operation deadline.

bool	writeCommand (GPSConfigurationStep step, QByteArrayView bytes)
	Starts one command attempt under its own deadline scope and writes it; awaitReply() waits for its reply.

GPSConfigurationEvidence	awaitReply (GPSReplyPoll reply)
	Decodes received traffic until reply resolves the current command, its deadline expires, or I/O fails.

GPSConfigurationEvidence	transact (GPSConfigurationStep step, QByteArrayView bytes)

GPSConfigurationEvidence	transact (GPSConfigurationStep step, QByteArrayView bytes, GPSTextMatcher reply)
	As above, also resolved by reply from each text reply a decoder offers.

GPSConfigurationEvidence	transact (GPSConfigurationStep step, QByteArrayView bytes, GPSFrameMatcher reply)
	As above, also resolved by reply from each dispatched frame.

GPSConfigurationEvidence	transact (const GPSCommandSequence::Command &command)

GPSCommandSequence::Result	runSequence (const GPSCommandSequence &sequence)
	Runs sequence in order until a required step fails or I/O fails; failed attempts retry up to their count.

bool	runRequired (const GPSCommandSequence &sequence)
	Runs sequence and fails control over a failed step as failSequence() does.

GPSBaudDetection	detectBaud (std::span< const unsigned > candidates, unsigned baud, GPSBaudProbeFunction probe)

GPSReceiveUpdates	receiveCycle (std::chrono::milliseconds timeout)

void	receiveFor (std::chrono::milliseconds duration)
	Repeats the family's full streaming receive until duration has passed or I/O fails.

bool	receiveUntil (std::function< bool()> done, std::chrono::milliseconds duration)

void	serviceControls ()
	Runs the family's streaming services once under SERVICE_TIMEOUT, then flushes. Nested calls do nothing.

GPSReceiveUpdates	flush ()
	Flushes decoder state and delivers the resulting batch.

GPSStreamDemux &	stream ()

GPSDecodeContext &	context ()

GPSLogCategory	logCategory () const

Static Public Attributes
static constexpr size_t	READ_CHUNK_SIZE = 150
	Bytes requested by each receive or reply read.

static constexpr std::chrono::milliseconds	SERVICE_TIMEOUT {5000}
	Budget of the streaming services that run after each receive.

Friends
class	GPSDeadlineScope

class	GPSDecodeContext

class	GPSProtocolRuntime

Detailed Description

The only I/O surface of a configurator or streaming service. Operations block on the caller thread; the runtime performs their I/O through its GPSRuntimeIO. After a sticky failure (a transport fault, cancellation or protocol failure), every operation returns failure immediately without I/O, so protocol code needs no failure checks between steps. Each command attempt records evidence: its label, outcome, start and finish, and the accepted, written and uncertain byte counts of the writes it made.

Definition at line 82 of file GPSCommandChannel.h.

Member Function Documentation

◆ awaitReply()

GPSConfigurationEvidence GPSCommandChannel::awaitReply ( GPSReplyPoll reply )

Decodes received traffic until reply resolves the current command, its deadline expires, or I/O fails.

Definition at line 304 of file GPSCommandChannel.cc.

References completeCommand(), deadlineScope(), failureOutcome(), nowUs(), Pending, GPSDeadline::remaining(), TimedOut, and GPSDeadline::untilUs.

◆ beginCommand()

void GPSCommandChannel::beginCommand ( GPSConfigurationStep step )

Starts a command attempt: retires a pending one as Written, stamps the start and sets its deadline. After a sticky failure no attempt starts: a completed attempt is replaced by this one, already ended by the failure.

Definition at line 134 of file GPSCommandChannel.cc.

References GPSDeadline::after(), GPSConfigurationEvidence::command, GPSConfigurationStep::command, failed(), finishCommand(), nowUs(), GPSConfigurationEvidence::required, GPSConfigurationStep::required, GPSConfigurationEvidence::startedAtUs, GPSConfigurationStep::timeout, GPSDeadline::untilUs, and Written.

Referenced by writeCommand().

◆ commandDeadline()

GPSDeadline GPSCommandChannel::commandDeadline ( ) const

inline

Deadline of the current command attempt, set by beginCommand().

Definition at line 99 of file GPSCommandChannel.h.

◆ completeCommand()

GPSConfigurationEvidence GPSCommandChannel::completeCommand ( GPSCommandOutcome outcome )

Retires the current attempt and reports it; repeated completion returns the retained evidence unchanged.

Definition at line 153 of file GPSCommandChannel.cc.

References GPSConfigurationEvidence::outcome.

Referenced by awaitReply(), and finishCommand().

◆ context()

GPSDecodeContext & GPSCommandChannel::context ( )

The decoding context, for publishing events from configuration or streaming services. Events published between decodes join the next decoded batch.

Definition at line 521 of file GPSCommandChannel.cc.

◆ currentCommand()

const GPSConfigurationEvidence & GPSCommandChannel::currentCommand ( ) const

inline

Definition at line 144 of file GPSCommandChannel.h.

◆ deadlineScope() [1/2]

GPSDeadlineScope GPSCommandChannel::deadlineScope ( GPSDeadline deadline )

inline

Definition at line 103 of file GPSCommandChannel.h.

◆ deadlineScope() [2/2]

GPSDeadlineScope GPSCommandChannel::deadlineScope ( std::chrono::milliseconds timeout )

inline

Definition at line 101 of file GPSCommandChannel.h.

Referenced by awaitReply(), GPSProtocolRuntime::probe(), receiveCycle(), serviceControls(), and writeCommand().

◆ detectBaud()

GPSBaudDetection GPSCommandChannel::detectBaud	(	std::span< const unsigned >	candidates,
		unsigned	baud,
		GPSBaudProbeFunction	probe
	)

Tries each of candidates, or only baud when it is nonzero, until probe finds the receiver at the rate the link was set to. A candidate the link cannot run at is skipped; a link failure, a Stop result, or a sticky failure ends the search. Without baud, the rate receiver detection found (GPSConfig::detectedBaud) is tried first, even when it is not a candidate.

Definition at line 412 of file GPSCommandChannel.cc.

References GPSBaudDetection::baud, Configured, failed(), Found, Stop, and Unsupported.

Referenced by UBX::Protocol::configure().

◆ error()

GPSProtocolError GPSCommandChannel::error ( ) const

inline

Definition at line 109 of file GPSCommandChannel.h.

Referenced by GPSProtocolRuntime::error().

◆ errorDetail()

const QString & GPSCommandChannel::errorDetail ( ) const

inline

Definition at line 111 of file GPSCommandChannel.h.

Referenced by GPSProtocolRuntime::configure(), and GPSProtocolRuntime::errorDetail().

◆ failControl() [1/2]

void GPSCommandChannel::failControl ( const QString & detail )

Records a protocol failure described by detail unless a failure is already recorded, whose detail stays.

Definition at line 65 of file GPSCommandChannel.cc.

References failed(), and Protocol.

◆ failControl() [2/2]

void GPSCommandChannel::failControl ( GPSProtocolError failure = GPSProtocolError::Protocol )

Records failure, Protocol or ConsentRequired, unless a failure is already recorded; clears the detail it replaces.

Definition at line 57 of file GPSCommandChannel.cc.

References failed().

Referenced by GPSProtocolRuntime::configure(), UBX::Protocol::configure(), GPSDecodeContext::failControl(), failNoAnswer(), failSequence(), and UBX::Protocol::serviceStreaming().

◆ failed()

bool GPSCommandChannel::failed ( ) const

inline

Definition at line 107 of file GPSCommandChannel.h.

References None.

Referenced by beginCommand(), UBX::Protocol::configure(), detectBaud(), failControl(), failControl(), GPSDecodeContext::failed(), read(), receiveCycle(), receiveFor(), receiveUntil(), runSequence(), serviceControls(), wait(), and write().

◆ failNoAnswer()

void GPSCommandChannel::failNoAnswer ( std::span< const unsigned > rates )

Fails control as no receiver of the family answering at rates, or as the link refusing the requested rate when none was probed, unless a failure is already recorded.

Definition at line 95 of file GPSCommandChannel.cc.

References failControl(), GPSProtocolRuntime::family(), gpsRateList(), gpsReceiverName(), and GPSReceiverFamily::type.

Referenced by UBX::Protocol::configure().

◆ failSequence()

void GPSCommandChannel::failSequence ( const GPSCommandSequence::Result & result )

Fails control over the command that ended result, naming it and the family's receiver in the detail, unless a transport failure or cancellation already failed the attempt.

Definition at line 81 of file GPSCommandChannel.cc.

References failControl(), GPSCommandSequence::Result::failedLabel, and GPSCommandSequence::Result::outcome.

Referenced by runRequired().

◆ failureOutcome()

GPSCommandOutcome GPSCommandChannel::failureOutcome ( ) const

The command outcome that reports the sticky failure; Pending while healthy.

Definition at line 103 of file GPSCommandChannel.cc.

References Cancelled, ConsentRequired, InvalidArgument, None, Pending, Protocol, Transport, and TransportError.

Referenced by awaitReply().

◆ finishCommand()

void GPSCommandChannel::finishCommand ( GPSCommandOutcome outcome )

inline

Definition at line 142 of file GPSCommandChannel.h.

References completeCommand().

Referenced by beginCommand(), GPSProtocolRuntime::configure(), GPSProtocolRuntime::probe(), and write().

◆ flush()

GPSReceiveUpdates GPSCommandChannel::flush ( )

Flushes decoder state and delivers the resulting batch.

Returns: its updates.

Definition at line 511 of file GPSCommandChannel.cc.

References GPSProtocolRuntime::consume().

Referenced by serviceControls().

◆ logCategory()

GPSLogCategory GPSCommandChannel::logCategory ( ) const

Definition at line 526 of file GPSCommandChannel.cc.

References GPSProtocolRuntime::logCategory().

Referenced by read().

◆ nowUs()

uint64_t GPSCommandChannel::nowUs ( ) const

Definition at line 52 of file GPSCommandChannel.cc.

Referenced by awaitReply(), beginCommand(), GPSDecodeContext::nowUs(), read(), GPSNMEAStream::receive(), receiveCycle(), receiveFor(), receiveUntil(), wait(), and write().

◆ operationDeadline()

GPSDeadline GPSCommandChannel::operationDeadline ( ) const

inline

Definition at line 96 of file GPSCommandChannel.h.

◆ read()

int GPSCommandChannel::read	(	std::span< uint8_t >	buffer,
		std::chrono::milliseconds	timeout
	)

Reads raw bytes without decoding them.

Returns: bytes read, 0 when nothing arrived, or -1 after a sticky failure.

Definition at line 166 of file GPSCommandChannel.cc.

References GPSDeadline::after(), Cancelled, Data, failed(), logCategory(), nowUs(), GPSRuntimeIO::read, TimedOut, Transport, and GPSDeadline::untilUs.

Referenced by receiveCycle().

◆ receiveCycle()

GPSReceiveUpdates GPSCommandChannel::receiveCycle ( std::chrono::milliseconds timeout )

One receive cycle without streaming services: reads under timeout in the family's read slices until the family reports the cycle complete, the deadline passes, or I/O fails.

Returns: the accumulated updates.

Definition at line 450 of file GPSCommandChannel.cc.

References GPSFamilyProtocol::completeReceiveCycle(), GPSProtocolRuntime::consume(), deadlineScope(), failed(), GPSFamilyProtocol::nextReadSlice(), nowUs(), GPSProtocolRuntime::protocol(), read(), and GPSDeadline::untilUs.

Referenced by UBX::Protocol::configure(), GPSFamilyProtocol::receive(), GPSNMEAStream::receive(), and receiveUntil().

◆ receiveFor()

void GPSCommandChannel::receiveFor ( std::chrono::milliseconds duration )

Repeats the family's full streaming receive until duration has passed or I/O fails.

Definition at line 474 of file GPSCommandChannel.cc.

References GPSDeadline::after(), failed(), nowUs(), GPSProtocolRuntime::protocol(), GPSFamilyProtocol::receive(), GPSDeadline::remaining(), and GPSDeadline::untilUs.

◆ receiveUntil()

bool GPSCommandChannel::receiveUntil	(	std::function< bool()>	done,
		std::chrono::milliseconds	duration
	)

Repeats receive cycles until done, duration has passed, or I/O fails.

Returns: whether done holds; false after a sticky failure.

Definition at line 485 of file GPSCommandChannel.cc.

References GPSDeadline::after(), failed(), nowUs(), receiveCycle(), GPSDeadline::remaining(), and GPSDeadline::untilUs.

◆ runRequired()

bool GPSCommandChannel::runRequired ( const GPSCommandSequence & sequence )

Runs sequence and fails control over a failed step as failSequence() does.

Returns: whether it succeeded.

Definition at line 403 of file GPSCommandChannel.cc.

References failSequence(), and runSequence().

◆ runSequence()

GPSCommandSequence::Result GPSCommandChannel::runSequence ( const GPSCommandSequence & sequence )

Runs sequence in order until a required step fails or I/O fails; failed attempts retry up to their count.

Definition at line 384 of file GPSCommandChannel.cc.

References GPSCommandSequence::Command::attempts, GPSConfigurationStep::command, failed(), GPSCommandSequence::Result::failedStep, GPSConfigurationEvidence::outcome, GPSConfigurationStep::required, GPSCommandSequence::Command::step, GPSCommandSequence::steps, GPSConfigurationEvidence::succeeded(), and transact().

Referenced by runRequired().

◆ serviceControls()

void GPSCommandChannel::serviceControls ( )

Runs the family's streaming services once under SERVICE_TIMEOUT, then flushes. Nested calls do nothing.

Definition at line 497 of file GPSCommandChannel.cc.

References deadlineScope(), failed(), flush(), GPSProtocolRuntime::protocol(), SERVICE_TIMEOUT, and GPSFamilyProtocol::serviceStreaming().

Referenced by GPSFamilyProtocol::receive(), and GPSNMEAStream::receive().

◆ setBaudrate()

bool GPSCommandChannel::setBaudrate ( unsigned baudrate )

An unsupported change fails without a sticky failure; a failed one names the rate in the error detail.

Returns: true when the link runs at the requested rate.

Definition at line 261 of file GPSCommandChannel.cc.

References Configured.

◆ setErrorDetail()

void GPSCommandChannel::setErrorDetail ( const QString & detail )

inline

Definition at line 113 of file GPSCommandChannel.h.

◆ stream()

GPSStreamDemux & GPSCommandChannel::stream ( )

Definition at line 516 of file GPSCommandChannel.cc.

References GPSProtocolRuntime::stream().

Referenced by UBX::Protocol::configure(), and GPSDecodeContext::stream().

◆ transact() [1/4]

GPSConfigurationEvidence GPSCommandChannel::transact ( const GPSCommandSequence::Command & command )

As above, for one command of a sequence: its step, bytes and text reply, or its raw reply matched in the received bytes.

Definition at line 375 of file GPSCommandChannel.cc.

References GPSCommandSequence::Command::reply, GPSCommandSequence::Command::step, transact(), and GPSCommandSequence::Command::wire.

◆ transact() [2/4]

GPSConfigurationEvidence GPSCommandChannel::transact	(	GPSConfigurationStep	step,
		QByteArrayView	bytes
	)

inline

Writes bytes and waits until a decoder resolves the reply through GPSDecodeContext, the step times out, or I/O fails. Received traffic keeps decoding while the reply is pending.

Definition at line 173 of file GPSCommandChannel.h.

Referenced by UBX::Protocol::probe(), runSequence(), and transact().

◆ transact() [3/4]

GPSConfigurationEvidence GPSCommandChannel::transact	(	GPSConfigurationStep	step,
		QByteArrayView	bytes,
		GPSFrameMatcher	reply
	)

inline

As above, also resolved by reply from each dispatched frame.

Definition at line 185 of file GPSCommandChannel.h.

◆ transact() [4/4]

GPSConfigurationEvidence GPSCommandChannel::transact	(	GPSConfigurationStep	step,
		QByteArrayView	bytes,
		GPSTextMatcher	reply
	)

inline

As above, also resolved by reply from each text reply a decoder offers.

Definition at line 179 of file GPSCommandChannel.h.

◆ wait()

void GPSCommandChannel::wait ( std::chrono::microseconds duration )

Waits for duration, capped by the operation deadline.

Definition at line 283 of file GPSCommandChannel.cc.

References Cancelled, GPSRuntimeIO::clock, failed(), nowUs(), GPSDeadline::untilUs, and GPSClock::wait.

◆ write()

bool GPSCommandChannel::write ( QByteArrayView bytes )

Writes all of bytes under the current command deadline. A null view is an invalid argument. A command that is late before any of its bytes were written, whether found here or by the transport, or an unsupported write, fails the current command without a sticky failure.

Returns: true when every byte was accepted and written.

Definition at line 200 of file GPSCommandChannel.cc.

References GPSConfigurationEvidence::acceptedBytes, Cancelled, GPSRuntimeIO::cancelToken, GPSConfigurationEvidence::command, Completed, failed(), GPSProtocolRuntime::family(), finishCommand(), gpsReceiverName(), InvalidArgument, GPSCancelToken::isCancelled(), nowUs(), TimedOut, Transport, TransportError, GPSReceiverFamily::type, Unsupported, GPSDeadline::untilUs, GPSRuntimeIO::write, and GPSConfigurationEvidence::writtenBytes.

Referenced by writeCommand().

◆ writeCommand()

bool GPSCommandChannel::writeCommand	(	GPSConfigurationStep	step,
		QByteArrayView	bytes
	)

Starts one command attempt under its own deadline scope and writes it; awaitReply() waits for its reply.

Definition at line 297 of file GPSCommandChannel.cc.

References beginCommand(), deadlineScope(), GPSConfigurationStep::timeout, and write().

Friends And Related Symbol Documentation

◆ GPSDeadlineScope

friend class GPSDeadlineScope

friend

Definition at line 236 of file GPSCommandChannel.h.

◆ GPSDecodeContext

friend class GPSDecodeContext

friend

Definition at line 237 of file GPSCommandChannel.h.

◆ GPSProtocolRuntime

friend class GPSProtocolRuntime

friend

Definition at line 238 of file GPSCommandChannel.h.

Member Data Documentation

◆ READ_CHUNK_SIZE

constexpr size_t GPSCommandChannel::READ_CHUNK_SIZE = 150

staticconstexpr

Bytes requested by each receive or reply read.

Definition at line 86 of file GPSCommandChannel.h.

◆ SERVICE_TIMEOUT

constexpr std::chrono::milliseconds GPSCommandChannel::SERVICE_TIMEOUT {5000}

staticconstexpr

Budget of the streaming services that run after each receive.

Definition at line 88 of file GPSCommandChannel.h.

Referenced by serviceControls().

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

src/GPS/Core/Protocols/GPSCommandChannel.h
src/GPS/Core/Protocols/GPSCommandChannel.cc

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ awaitReply()

◆ beginCommand()

◆ commandDeadline()

◆ completeCommand()

◆ context()

◆ currentCommand()

◆ deadlineScope() [1/2]

◆ deadlineScope() [2/2]

◆ detectBaud()

◆ error()

◆ errorDetail()

◆ failControl() [1/2]

◆ failControl() [2/2]

◆ failed()

◆ failNoAnswer()

◆ failSequence()

◆ failureOutcome()

◆ finishCommand()

◆ flush()

◆ logCategory()

◆ nowUs()

◆ operationDeadline()

◆ read()

◆ receiveCycle()

◆ receiveFor()

◆ receiveUntil()

◆ runRequired()

◆ runSequence()

◆ serviceControls()

◆ setBaudrate()

◆ setErrorDetail()

◆ stream()

◆ transact() [1/4]

◆ transact() [2/4]

◆ transact() [3/4]

◆ transact() [4/4]

◆ wait()

◆ write()

◆ writeCommand()

Friends And Related Symbol Documentation

◆ GPSDeadlineScope

◆ GPSDecodeContext

◆ GPSProtocolRuntime

Member Data Documentation

◆ READ_CHUNK_SIZE

◆ SERVICE_TIMEOUT