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 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.

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.