nl::Weave::System::Layer

#include <src/system/SystemLayer.h>

This provides access to timers according to the configured event handling model.

Summary

For WEAVE_SYSTEM_CONFIG_USE_SOCKETS, event readiness notification is handled via traditional poll/select implementation on the platform adaptation.

For WEAVE_SYSTEM_CONFIG_USE_LWIP, event readiness notification is handle via events / messages and platform- and system-specific hooks for the event/message system.

Constructors and Destructors
`Layer(void)`

Public types
`EventHandler)(Object &aTarget, EventType aEventType, uintptr_t aArgument)`	typedef `Error(*`
`TimerCompleteFunct)(Layer aLayer, void aAppState, Error aError)`	typedef `void(*`

Public functions
`AddEventHandlerDelegate(LwIPEventHandlerDelegate & aDelegate)`	`Error` This adds an event handler delegate to the system layer to extend its ability to handle LwIP events.
`CancelTimer(TimerCompleteFunct aOnComplete, void *aAppState)`	`void` This method cancels a one-shot timer, started earlier through `StartTimer()`.
`DispatchEvent(Event aEvent)`	`Error` This dispatches the specified event for handling by this instance.
`DispatchEvents(void)`	`Error` This is a syntactic wrapper around a platform-specific hook that effects an event loop, waiting on a queue that services this instance, pulling events off of that queue, and then dispatching them for handling.
`GetPlatformData(void) const`	`void *` This returns any client-specific platform data assigned to the instance, if it has been previously set.
`HandleEvent(Object & aTarget, EventType aEventType, uintptr_t aArgument)`	`Error` This implements the actual dispatch and handling of a Weave System Layer event.
`HandlePlatformTimer(void)`	`Error` Handle the platform timer expiration event.
`HandleSelectResult(int aSetSize, fd_set aReadSet, fd_set aWriteSet, fd_set *aExceptionSet)`	`void` Handle I/O from a select call.
`Init(void *aContext)`	`Error`
`NewTimer(Timer *& aTimerPtr)`	`Error`
`PostEvent(Object & aTarget, EventType aEventType, uintptr_t aArgument)`	`Error` This posts an event / message of the specified type with the provided argument to this instance's platform-specific event queue.
`PrepareSelect(int & aSetSize, fd_set aReadSet, fd_set aWriteSet, fd_set *aExceptionSet, struct timeval & aSleepTime)`	`void` Prepare the sets of file descriptors for `select()` to work with.
`ScheduleWork(TimerCompleteFunct aComplete, void *aAppState)`	`Error` Schedules a function with a signature identical to `TimerCompleteFunct` to be run as soon as possible on the Weave thread.
`SetPlatformData(void *aPlatformData)`	`void` This sets the specified client-specific platform data to the instance for later retrieval by the client platform.
`Shutdown(void)`	`Error`
`StartTimer(uint32_t aMilliseconds, TimerCompleteFunct aComplete, void *aAppState)`	`Error` This method starts a one-shot timer.
`State(void) const`	`LayerState` This returns the current state of the layer object.
`WakeSelect(void)`	`void` Wake up the I/O thread that monitors the file descriptors using select() by writing a single byte to the wake pipe.

Public static functions
`GetClock_Monotonic(void)`	`uint64_t` Returns a monotonic system time in units of microseconds.
`GetClock_MonotonicHiRes(void)`	`uint64_t` Returns a (potentially) high-resolution monotonic system time in units of microseconds.
`GetClock_MonotonicMS(void)`	`uint64_t` Returns a monotonic system time in units of milliseconds.
`GetClock_RealTime(uint64_t & curTime)`	`Error` Returns the current real (civil) time in microsecond Unix time format.
`GetClock_RealTimeMS(uint64_t & curTimeMS)`	`Error` Returns the current real (civil) time in millisecond Unix time format.
`SetClock_RealTime(uint64_t newCurTime)`	`Error` Sets the platform's notion of current real (civil) time.

Public types

EventHandler

Error(* EventHandler)(Object &aTarget, EventType aEventType, uintptr_t aArgument)

TimerCompleteFunct

void(* TimerCompleteFunct)(Layer *aLayer, void *aAppState, Error aError)

Public functions

AddEventHandlerDelegate

Error AddEventHandlerDelegate(
  LwIPEventHandlerDelegate & aDelegate
)

This adds an event handler delegate to the system layer to extend its ability to handle LwIP events.

Details

Parameters

[in] aDelegate

An uninitialied LwIP event handler delegate structure

Return Values

`WEAVE_SYSTEM_NO_ERROR`	On success.
`WEAVE_SYSTEM_ERROR_BAD_ARGS`	If the function pointer contained in aDelegate is NULL

CancelTimer

void CancelTimer(
  TimerCompleteFunct aOnComplete,
  void *aAppState
)

This method cancels a one-shot timer, started earlier through StartTimer().

Details

Parameters

`[in] aOnComplete`	A pointer to the callback function used in calling `StartTimer()`.
`[in] aAppState`	A pointer to the application state object used in calling `StartTimer()`.

DispatchEvent

Error DispatchEvent(
  Event aEvent
)

This dispatches the specified event for handling by this instance.

The unmarshalling of the type and arguments from the event is handled by a platform-specific hook which should then call back to Layer::HandleEvent for the actual dispatch.

Details

Parameters

[in] aEvent

The platform-specific event object to dispatch for handling.

Returns

WEAVE_SYSTEM_NO_ERROR on success; otherwise, a specific error indicating the reason for initialization failure.

DispatchEvents

Error DispatchEvents(
  void
)

This is a syntactic wrapper around a platform-specific hook that effects an event loop, waiting on a queue that services this instance, pulling events off of that queue, and then dispatching them for handling.

Details
Returns	WEAVE_SYSTEM_NO_ERROR on success; otherwise, a specific error indicating the reason for initialization failure.

GetPlatformData

void * GetPlatformData(
  void
) const

This returns any client-specific platform data assigned to the instance, if it has been previously set.

Details
Returns	Client-specific platform data, if is has been previously set; otherwise, NULL.

HandleEvent

Error HandleEvent(
  Object & aTarget,
  EventType aEventType,
  uintptr_t aArgument
)

This implements the actual dispatch and handling of a Weave System Layer event.

Details

Parameters

`[in,out] aTarget`	A reference to the layer object to which the event is targeted.
`[in] aEventType`	The event / message type to handle.
`[in] aArgument`	The argument associated with the event / message.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	On success.
`WEAVE_SYSTEM_ERROR_UNEXPECTED_STATE`	If the state of the InetLayer object is incorrect.
`WEAVE_SYSTEM_ERROR_UNEXPECTED_EVENT`	If the event type is unrecognized.

HandlePlatformTimer

Error HandlePlatformTimer(
  void
)

Handle the platform timer expiration event.

Calls nl::Weave::System::Timer::HandleExpiredTimers to handle any expired timers. It is assumed that this API is called only while on the thread which owns the Weave System Layer object.

Details
Returns	WEAVE_SYSTEM_NO_ERROR on success, error code otherwise.

HandleSelectResult

void HandleSelectResult(
  int aSetSize,
  fd_set *aReadSet,
  fd_set *aWriteSet,
  fd_set *aExceptionSet
)

Handle I/O from a select call.

This method registers the pending I/O event in each active endpoint and then invokes the respective I/O handling functions for those endpoints.

Details

Parameters

`[in] aSetSize`	The return value of the select call.
`[in] aReadSet`	A pointer to the set of read file descriptors.
`[in] aWriteSet`	A pointer to the set of write file descriptors.
`[in] aExceptionSet`	A pointer to the set of file descriptors with errors.

Init

Error Init(
  void *aContext
)

Layer

 Layer(
  void
)

NewTimer

Error NewTimer(
  Timer *& aTimerPtr
)

PostEvent

Error PostEvent(
  Object & aTarget,
  EventType aEventType,
  uintptr_t aArgument
)

This posts an event / message of the specified type with the provided argument to this instance's platform-specific event queue.

Details

Parameters

`[in,out] aTarget`	A pointer to the Weave System Layer object making the post request.
`[in] aEventType`	The type of event to post.
`[in,out] aArgument`	The argument associated with the event to post.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	On success.
`WEAVE_SYSTEM_ERROR_UNEXPECTED_STATE`	If the state of the Layer object is incorrect.
`WEAVE_SYSTEM_ERROR_NO_MEMORY`	If the event queue is already full.
`other`	Platform-specific errors generated indicating the reason for failure.

PrepareSelect

void PrepareSelect(
  int & aSetSize,
  fd_set *aReadSet,
  fd_set *aWriteSet,
  fd_set *aExceptionSet,
  struct timeval & aSleepTime
)

Prepare the sets of file descriptors for select() to work with.

Details

Parameters

`[out] aSetSize`	The range of file descriptors in the file descriptor set.
`[in] aReadSet`	A pointer to the set of readable file descriptors.
`[in] aWriteSet`	A pointer to the set of writable file descriptors.
`[in] aExceptionSet`	A pointer to the set of file descriptors with errors.
`[in] aSleepTime`	A reference to the maximum sleep time.

ScheduleWork

Error ScheduleWork(
  TimerCompleteFunct aComplete,
  void *aAppState
)

Schedules a function with a signature identical to TimerCompleteFunct to be run as soon as possible on the Weave thread.

Note: This function could, in principle, be implemented as StartTimer(0, aComplete, aAppState). The specification for SystemTimer however permits certain optimizations that might make that implementation impossible. Specifically, SystemTimer API may only be called from the thread owning the particular SystemLayer, whereas the ScheduleWork may be called from any thread. Additionally, whereas the SystemTimer API permits the invocation of the already expired handler in line, ScheduleWork guarantees that the handler function will be called only after the current Weave event completes.

Details

Parameters

`[in] aComplete`	A pointer to a callback function to be called when this timer fires.
`[in] aAppState`	A pointer to an application state object to be passed to the callback function as argument.

Return Values

`WEAVE_SYSTEM_ERROR_UNEXPECTED_STATE`	If the SystemLayer has not been initialized.
`WEAVE_SYSTEM_ERROR_NO_MEMORY`	If the SystemLayer cannot allocate a new timer.
`WEAVE_SYSTEM_NO_ERROR`	On success.

SetPlatformData

void SetPlatformData(
  void *aPlatformData
)

This sets the specified client-specific platform data to the instance for later retrieval by the client platform.

Details

Parameters

[in] aPlatformData

The client-specific platform data to set.

Shutdown

Error Shutdown(
  void
)

StartTimer

Error StartTimer(
  uint32_t aMilliseconds,
  TimerCompleteFunct aComplete,
  void *aAppState
)

This method starts a one-shot timer.

Details

Parameters

`[in] aMilliseconds`	Expiration time in milliseconds.
`[in] aComplete`	A pointer to the function called when timer expires.
`[in] aAppState`	A pointer to the application state object used when timer expires.

Returns

WEAVE_SYSTEM_NO_ERROR On success.

Returns

WEAVE_SYSTEM_ERROR_NO_MEMORY If a timer cannot be allocated.

Returns

Other Value indicating timer failed to start.

State

LayerState State(
  void
) const

This returns the current state of the layer object.

WakeSelect

void WakeSelect(
  void
)

Wake up the I/O thread that monitors the file descriptors using select() by writing a single byte to the wake pipe.

Note:If WakeSelect() is being called from within HandleSelectResult(), then writing to the wake pipe can be skipped, since the I/O thread is already awake. Furthermore, we don't care if this write fails as the only reasonably likely failure is that the pipe is full, in which case the select calling thread is going to wake up anyway.

Public static functions

GetClock_Monotonic

uint64_t GetClock_Monotonic(
  void
)

Returns a monotonic system time in units of microseconds.

This function returns an elapsed time in microseconds since an arbitrary, platform-defined epoch. The value returned is guaranteed to be ever-increasing (i.e. never wrapping) between reboots of the system. Additionally, the underlying time source is guaranteed to tick continuously during any system sleep modes that do not entail a restart upon wake.

Although some platforms may choose to return a value that measures the time since boot for the system, applications must not rely on this. Additionally, the epoch for GetClock_Monotonic() is not required to be the same as that for any of the other GetClock... functions. Therefore relative time calculations can only be performed on values returned by the same function.

This function is guaranteed to be thread-safe on any platform that employs threading.

Details
Returns	Elapsed time in microseconds since an arbitrary, platform-defined epoch.

GetClock_MonotonicHiRes

uint64_t GetClock_MonotonicHiRes(
  void
)

Returns a (potentially) high-resolution monotonic system time in units of microseconds.

This function returns an elapsed time in microseconds since an arbitrary, platform-defined epoch. The value returned is guaranteed to be ever-increasing (i.e. never wrapping) between reboots of the system. However, the underlying timer is not required to tick continuously during system deep-sleep states.

Some platforms may implement GetClock_MonotonicHiRes() using a high-resolution timer capable of greater precision than GetClock_Monotonic(), and that is not subject to gradual clock adjustments (slewing). Systems without such a timer may simply return the same value as GetClock_Monotonic().

The epoch for time returned by GetClock_MonotonicHiRes() is not required to be the same that for any of the other GetClock... functions, including GetClock_Monotonic().

This function is guaranteed to be thread-safe on any platform that employs threading.

Details
Returns	Elapsed time in microseconds since an arbitrary, platform-defined epoch.

GetClock_MonotonicMS

uint64_t GetClock_MonotonicMS(
  void
)

Returns a monotonic system time in units of milliseconds.

This function returns an elapsed time in milliseconds since an arbitrary, platform-defined epoch. The value returned is guaranteed to be ever-increasing (i.e. never wrapping) between reboots of the system. Additionally, the underlying time source is guaranteed to tick continuously during any system sleep modes that do not entail a restart upon wake.

This function is guaranteed to be thread-safe on any platform that employs threading.

Details
Returns	Elapsed time in milliseconds since an arbitrary, platform-defined epoch.

GetClock_RealTime

Error GetClock_RealTime(
  uint64_t & curTime
)

Returns the current real (civil) time in microsecond Unix time format.

This method returns the local platform's notion of current real time, expressed as a Unix time value scaled to microseconds. The underlying clock is guaranteed to tick at a rate of least at whole seconds (values of 1,000,000), but on some platforms may tick faster.

If the underlying platform is capable of tracking real time, but the system is currently unsynchronized, GetClock_RealTime() will return the error WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED.

On platforms that are incapable of tracking real time, the GetClock_RealTime() method may be absent, resulting a link error for any application that references it. Alternatively, such platforms may supply an implementation of GetClock_RealTime() that always returns the error WEAVE_SYSTEM_ERROR_NOT_SUPPORTED.

This function is guaranteed to be thread-safe on any platform that employs threading.

Details

Parameters

[out] curTime

The current time, expressed as Unix time scaled to microseconds.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	If the method succeeded.
`#WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED`	If the platform is capable of tracking real time, but is is currently unsynchronized.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If the platform is incapable of tracking real time.

GetClock_RealTimeMS

Error GetClock_RealTimeMS(
  uint64_t & curTimeMS
)

Returns the current real (civil) time in millisecond Unix time format.

This method returns the local platform's notion of current real time, expressed as a Unix time value scaled to milliseconds. The underlying clock is guaranteed to tick at a rate of least at whole seconds (values of 1,000,000), but on some platforms may tick faster.

If the underlying platform is capable of tracking real time, but the system is currently unsynchronized, GetClock_RealTimeMS() will return the error WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED.

On platforms that are incapable of tracking real time, the GetClock_RealTimeMS() method may be absent, resulting a link error for any application that references it. Alternatively, such platforms may supply an implementation of GetClock_RealTimeMS() that always returns the error WEAVE_SYSTEM_ERROR_NOT_SUPPORTED.

This function is guaranteed to be thread-safe on any platform that employs threading.

Details

Parameters

[out] curTime

The current time, expressed as Unix time scaled to milliseconds.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	If the method succeeded.
`#WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED`	If the platform is capable of tracking real time, but is is currently unsynchronized.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If the platform is incapable of tracking real time.

SetClock_RealTime

Error SetClock_RealTime(
  uint64_t newCurTime
)

Sets the platform's notion of current real (civil) time.

Applications can call this function to set the local platform's notion of current real time. The new current time is expressed as a Unix time value scaled to microseconds.

Once set, underlying platform clock is guaranteed to track real time with a granularity of at least whole seconds.

Some platforms may restrict which applications or processes can set real time. If the caller is not permitted to change real time, the SetClock_RealTime() function will return the error WEAVE_SYSTEM_ERROR_ACCESS_DENIED.

On platforms that are incapable of tracking real time, or do not offer the ability to set real time, the SetClock_RealTime() function may be absent, resulting a link error for any application that references it. Alternatively, such platforms may supply an implementation of SetClock_RealTime() that always returns the error WEAVE_SYSTEM_ERROR_NOT_SUPPORTED.

This function is guaranteed to be thread-safe on any platform that employs threading.

Details

Parameters

[in] newCurTime

The new current time, expressed as Unix time scaled to microseconds.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	If the method succeeded.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If the platform is incapable of tracking real time.
`#WEAVE_SYSTEM_ERROR_ACCESS_DENIED`	If the calling application does not have the privilege to set the current time.

nl::Weave::System::Layer

Summary

Constructors and Destructors

Public types

Public functions

Public static functions

Public types

EventHandler

TimerCompleteFunct

Public functions

AddEventHandlerDelegate

CancelTimer

DispatchEvent

DispatchEvents

GetPlatformData

HandleEvent

HandlePlatformTimer

HandleSelectResult

Init

Layer

NewTimer

PostEvent

PrepareSelect

ScheduleWork

SetPlatformData

Shutdown

StartTimer

State

WakeSelect

Public static functions

GetClock_Monotonic

GetClock_MonotonicHiRes

GetClock_MonotonicMS

GetClock_RealTime

GetClock_RealTimeMS

SetClock_RealTime