messaging

template<typename messageType>
class ReadFunctor : public ReadFunctorBase

#include <messaging.h>

Read functors have read-only access to messages

Public Functions

ReadFunctor() = default

constructor

inline ReadFunctor(messageType *payloadPtr, MsgHeader *headerPtr)

constructor

inline ~ReadFunctor()

destructor &#8212; REQUIRED for the #676 keep-alive: a ReadFunctor is usually a C++ member of a module, so SWIG extend destructors never run for it; only this real C++ destructor does, and it must drop the Python reference held via releaseSource.

inline ReadFunctor(const ReadFunctor &other)

copy constructor &#8212; take an additional reference to the source

inline ReadFunctor &operator=(const ReadFunctor &other)

copy assignment &#8212; acquire the incoming owner before releasing and replacing ours

inline ReadFunctor(ReadFunctor &&other)

move constructor &#8212; steal the source token and null out the moved-from reader

inline ReadFunctor &operator=(ReadFunctor &&other)

move assignment &#8212; release ours, steal theirs, null out the moved-from reader

inline void setSource(void *handle, void (*acquire)(void*), void (*release)(void*))

Install (or replace) the opaque keep-alive source. Called only from the SWIG layer after a subscribe completes. The caller has already taken the one reference we adopt here (so we do NOT call acquire); subsequent C++ copies acquire, destructors release.

inline void *getSourceHandle() const

Return the opaque source owner retained by this reader.

Note

The caller must retain the handle before releasing this reader or changing its subscription. This accessor does not transfer ownership.

Returns:

Borrowed source handle, or nullptr if no owner is installed.

inline const messageType &operator()()

constructor

inline bool isLinked()

check if this msg has been connected to

inline bool isWritten()

check if the message has been ever written to

inline uint64_t timeWritten()

return the time at which the message was written

inline int64_t moduleID()

return the moduleID of who wrote wrote the message

inline void subscribeToC(void *source)

subscribe to a C message

inline void subscribeToAddr(uint64_t sourceAddr)

Subscribe to the message located at the sourceAddr in memory.

inline void subscribeToCAddr(uint64_t sourceAddr)

Subscribe to the C message located at the sourceAddr in memory.

inline void subscribeTo(Message<messageType> *source)

Subscribe to a C++ message.

inline void unsubscribe()

Unsubscribe to the connected message, noop if no message was connected.

inline uint8_t isSubscribedToC(void *source)

Check if self has been subscribed to a C message.

inline uint8_t isSubscribedTo(Message<messageType> *source)

Check if self has been subscribed to a Cpp message.

inline uint8_t isSubscribedToAddr(uint64_t sourceAddr)

Check if self has been subscribed to the message at sourceAddr.

inline uint8_t isSubscribedToCAddr(uint64_t sourceAddr)

Check if self has been subscribed to the message at sourceAddr.

inline Recorder<messageType> recorder(uint64_t timeDiff = 0)

Recorder method description.

inline uintptr_t getPayloadPtrAddress() const

Return the address of the internal payloadPointer member.

inline uintptr_t getLinkedAddress() const

Return the address of the internal initialized flag.

Public Members

BSKLogger bskLogger

< &#8212; BSK Logging

&#8212; bsk logging instance

messageType zeroMsgPayload = {}

&#8212; zero’d copy of the message payload type

Private Types

using SourceCallback = void (*)(void*)

Source-reference callback type used by the keep-alive bridge.

Private Functions

inline void releaseHandle_()

release our hold on the current source (if any), then forget it

inline void adoptHandleFrom_(const ReadFunctor &other)

copy the keep-alive trio from another reader and take an additional reference to it

Private Members

messageType *payloadPointer = nullptr

&#8212; pointer to the incoming msg data

MsgHeader *headerPointer = nullptr

&#8212; pointer to the incoming msg header

bool initialized = false

&#8212; flag indicating if the input message is connected to another message

void *sourceHandle = nullptr

&#8212; opaque owner token (a PyObject* in practice)

SourceCallback acquireSource = nullptr

&#8212; +1 the owner (Py_INCREF under the GIL)

SourceCallback releaseSource = nullptr

&#8212; -1 the owner (Py_DECREF under the GIL)

bool replacingSource = false

&#8212; prevents ownership changes during a release callback

class SourceReplacementGuard

keep replacement callbacks from changing the reader until the incoming state is committed

Public Functions

inline explicit SourceReplacementGuard(bool &replacementFlag)

inline ~SourceReplacementGuard()

Private Members

bool &flag

class SourceHandleGuard

own an acquired or transferred source reference until assignment commits it

Public Functions

inline SourceHandleGuard(void *handle, SourceCallback acquire, SourceCallback release, bool acquireReference)

inline ~SourceHandleGuard()

inline void relinquish()

Private Members

void *handle

SourceCallback release

template<typename messageType>
class WriteFunctor

#include <messaging.h>

Write Functor

Public Functions

inline WriteFunctor()

write functor constructor

inline WriteFunctor(messageType *payloadPointer, MsgHeader *headerPointer)

write functor constructor

inline void operator()(messageType *payload, int64_t moduleID, uint64_t callTime)

write functor constructor

Private Members

messageType *payloadPointer

pointer to the message payload

MsgHeader *headerPointer

pointer to the message header

template<typename messageType>
class Message : public MessageBase

#include <messaging.h>

forward-declare sim message for use by read functor

base class template for bsk messages

Public Functions

Message()

Message(const Message &other)

copy constructor

Message &operator=(const Message &other)

copy assignment operator

Message(Message &&other)

move constructor

Message &operator=(Message &&other)

move assignment operator

ReadFunctor<messageType> addSubscriber()

&#8212; request read rights. returns reference to class read variable

WriteFunctor<messageType> addAuthor()

&#8212; request write rights.

messageType *subscribeRaw(MsgHeader **msgPtr)

for plain ole c modules

messageType *getMsgPointers(MsgHeader **msgPtr)

for plain ole c modules

inline Recorder<messageType> recorder(uint64_t timeDiff = 0)

Recorder object.

inline bool isLinked()

check if this msg has been connected to

inline uint64_t getPayloadSize()

Return the memory size of the payload, be careful about dynamically sized things.

inline uintptr_t getPayloadAddress()

Return the raw address of the message payload struct.

inline uintptr_t getHeaderAddress()

Return the raw address of the message header struct.

Public Members

WriteFunctor<messageType> write = WriteFunctor<messageType>(&payload, &header)

write functor to this message

messageType zeroMsgPayload = {}

zero’d copy of the message payload structure

Private Members

messageType payload = {}

struct defining message payload, zero’d on creation

MsgHeader header = {}

struct defining the message header, zero’d on creation

ReadFunctor<messageType> read = ReadFunctor<messageType>(&payload, &header)

read functor instance

template<typename messageType>
class Recorder : public SysModel

#include <messaging.h>

Keep a time history of messages accessible to users from python

Public Functions

inline Recorder()

inline Recorder(Message<messageType> *message, uint64_t timeDiff = 0)

&#8212; Use this to record cpp messages

inline Recorder(void *message, uint64_t timeDiff = 0)

&#8212; Use this to record C messages

inline Recorder(ReadFunctor<messageType> *messageReader, uint64_t timeDiff = 0)

&#8212; Use this to keep track of what someone is reading

inline Recorder(const Recorder &obj)

&#8212; Copy recorder state while keeping a unique SysModel module ID

inline Recorder &operator=(const Recorder &obj)

&#8212; Copy recorder state while preserving this recorder’s module ID

inline ~Recorder()

inline void setSource(void *handle, void (*acquire)(void*), void (*release)(void*))

Install an opaque owner on the recorder’s reader for the SWIG keep-alive bridge.

inline void SelfInit()

&#8212; self initialization

inline void IntegratedInit()

&#8212; cross initialization

inline void UpdateState(uint64_t CurrentSimNanos)

&#8212; Read and record the message

inline void Reset(uint64_t CurrentSimNanos)

Reset method.

inline std::vector<unsigned long long> times()

recorded times, copied out as a std::vector so the Python interface is unchanged. The element type is “unsigned long long” (not uint64_t) to match the SWIG TimeVector template exactly; on LP64 platforms uint64_t is “unsigned long”, a distinct type that would fail to copy-construct.

inline std::vector<unsigned long long> timesWritten()

message-written times, copied out as a std::vector (see times() for the element-type rationale)

inline std::deque<messageType> &record()

internal accessor: the recorded-payload deque by reference, used by the SWIG recorder typemaps

inline std::vector<messageType> recordList()

recorded payloads copied out as a std::vector, exposed to Python so the result is randomly indexable

inline size_t size()

size of the record so far

inline std::string findMsgName(std::string msgName)

determine message name

inline void clear()

clear the recorded messages, i.e. purge the history

inline void updateTimeInterval(uint64_t timeDiff)

method to update the minimum time interval before recording the next message

inline void recordOnChange(bool enabled = true)

method to record messages only when the payload content changes

Public Members

BSKLogger bskLogger

&#8212; BSK Logging

Private Functions

inline void logInvalidMessageWarning()

log warning if message is invalid but don’t change behavior

inline void recordMessage(uint64_t CurrentSimNanos, const messageType &messageData)

record the supplied message payload

inline void scheduleNextUpdate(uint64_t CurrentSimNanos)

schedule the next eligible recorder update

inline bool messagePayloadChanged(const messageType &messageData)

check if the payload differs from the last recorded payload

inline void copyRecorderState(const Recorder &obj)

&#8212; Copy recorder-owned state without copying the SysModel identity

Private Members

std::deque<messageType> msgRecord

deque of recorded messages (deque avoids the geometric reallocation spikes a vector incurs as the history grows; see issue #788)

std::deque<uint64_t> msgRecordTimes

deque of times at which messages are recorded

std::deque<uint64_t> msgWrittenTimes

deque of times at which messages are written

uint64_t nextUpdateTime = 0

[ns] earliest time at which the msg is recorded again

uint64_t timeInterval = 0

[ns] recording time interval

uint64_t lastUpdateTime = 0

[ns] last time the msg was checked for recording

bool hasLastUpdateTime = false

flag indicating whether the msg was checked

bool recordOnlyOnChange = false

flag to record only changed message payloads

ReadFunctor<messageType> readMessage

method description