AWS IoT Device SDK C++ v2: Aws::Crt::Io::ChannelHandler Struct Reference

AWS IoT Device SDK C++ v2 1.14.0 AWS IoT Device SDK C++ v2

Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
Aws::Crt::Io::ChannelHandler Struct Referenceabstract

`#include <ChannelHandler.h>`

Inheritance diagram for Aws::Crt::Io::ChannelHandler:

## Public Member Functions
virtual | ~ChannelHandler ()=default
| ChannelHandler (const ChannelHandler &)=delete
ChannelHandler & | operator= (const ChannelHandler &)=delete
bool | ChannelsThreadIsCallersThread () const
void | ShutDownChannel (int errorCode)
void | ScheduleTask (std::function< void(TaskStatus)> &&task)
void | ScheduleTask (std::function< void(TaskStatus)> &&task, std::chrono::nanoseconds run_in)

## Public Attributes
| s_ProcessReadMessage
| s_ProcessWriteMessage
| s_IncrementReadWindow
| s_ProcessShutdown
| s_InitialWindowSize
| s_MessageOverhead
| s_ResetStatistics
| s_GatherStatistics

## Protected Member Functions
virtual int | ProcessReadMessage (struct aws_io_message *message)=0
virtual int | ProcessWriteMessage (struct aws_io_message *message)=0
virtual int | IncrementReadWindow (size_t size)=0
virtual void | ProcessShutdown (ChannelDirection dir, int errorCode, bool freeScarceResourcesImmediately)=0
virtual size_t | InitialWindowSize ()=0
virtual size_t | MessageOverhead ()=0
virtual void | ResetStatistics ()
virtual void | GatherStatistics (struct aws_array_list *)
| ChannelHandler (Allocator *allocator=g_allocator)
struct aws_io_message * | AcquireMessageFromPool (MessageType messageType, size_t sizeHint)
struct aws_io_message * | AcquireMaxSizeMessageForWrite ()
bool | SendMessage (struct aws_io_message *message, ChannelDirection direction)
bool | IncrementUpstreamReadWindow (size_t windowUpdateSize)
void | OnShutdownComplete (ChannelDirection direction, int errorCode, bool freeScarceResourcesImmediately)
size_t | DownstreamReadWindow () const
size_t | UpstreamMessageOverhead () const
struct aws_channel_slot * | GetSlot () const

## Protected Attributes
struct aws_channel_handler | m_handler
Allocator * | m_allocator

## Detailed Description

Wrapper for aws-c-io channel handlers. The semantics are identical as the functions on aws_channel_handler.

All virtual calls are made from the same thread (the channel's thread).

## Constructor & Destructor Documentation

## ◆ ~ChannelHandler()

virtual Aws::Crt::Io::ChannelHandler::~ChannelHandler | ( |  | ) |
| virtualdefault

## ◆ ChannelHandler() [1/2]

Aws::Crt::Io::ChannelHandler::ChannelHandler | ( | const ChannelHandler & |  | ) |
| delete

## ◆ ChannelHandler() [2/2]

Aws::Crt::Io::ChannelHandler::ChannelHandler | ( | Allocator * | allocator = `g_allocator` | ) |
| protected

## Member Function Documentation

## ◆ AcquireMaxSizeMessageForWrite()

struct aws_io_message * Aws::Crt::Io::ChannelHandler::AcquireMaxSizeMessageForWrite | ( |  | ) |
| protected

Convenience function that invokes AcquireMessageFromPool(), asking for the largest reasonable DATA message that can be sent in the write direction, with upstream overhead accounted for.

## ◆ AcquireMessageFromPool()

struct aws_io_message * Aws::Crt::Io::ChannelHandler::AcquireMessageFromPool | ( | MessageType | messageType,
|  | size_t | sizeHint
| ) |  |
| protected

Acquire an aws_io_message from the channel's pool.

## ◆ ChannelsThreadIsCallersThread()

bool Aws::Crt::Io::ChannelHandler::ChannelsThreadIsCallersThread | ( |  | ) | const

Return whether the caller is on the same thread as the handler's channel.

## ◆ DownstreamReadWindow()

size_t Aws::Crt::Io::ChannelHandler::DownstreamReadWindow | ( |  | ) | const
| protected

Fetches the downstream read window. This gives you the information necessary to honor the read window. If you call send_message() and it exceeds this window, the message will be rejected.

## ◆ GatherStatistics()

virtual void Aws::Crt::Io::ChannelHandler::GatherStatistics | ( | struct aws_array_list * |  | ) |
| inlineprotectedvirtual

Adds a pointer to the handler's internal statistics (if they exist) to a list of statistics structures associated with the channel's handler chain.

## ◆ GetSlot()

struct aws_channel_slot * Aws::Crt::Io::ChannelHandler::GetSlot | ( |  | ) | const
| protected

## ◆ IncrementReadWindow()

virtual int Aws::Crt::Io::ChannelHandler::IncrementReadWindow | ( | size_t | size | ) |
| protectedpure virtual

Called by the channel when a downstream handler has issued a window increment. You'll want to update your internal state and likely propagate a window increment message of your own by calling IncrementUpstreamReadWindow()

Returns
  AWS_OP_SUCCESS if successful. Otherwise, raise an error and return AWS_OP_ERR.

## ◆ IncrementUpstreamReadWindow()

bool Aws::Crt::Io::ChannelHandler::IncrementUpstreamReadWindow | ( | size_t | windowUpdateSize | ) |
| protected

Issue a window update notification upstream. Returns true if successful.

## ◆ InitialWindowSize()

virtual size_t Aws::Crt::Io::ChannelHandler::InitialWindowSize | ( |  | ) |
| protectedpure virtual

Called by the channel when the handler is added to a slot, to get the initial window size.

## ◆ MessageOverhead()

virtual size_t Aws::Crt::Io::ChannelHandler::MessageOverhead | ( |  | ) |
| protectedpure virtual

Called by the channel anytime a handler is added or removed, provides a hint for downstream handlers to avoid message fragmentation due to message overhead.

## ◆ OnShutdownComplete()

void Aws::Crt::Io::ChannelHandler::OnShutdownComplete | ( | ChannelDirection | direction,
|  | int | errorCode,
|  | bool | freeScarceResourcesImmediately
| ) |  |
| protected

Must be called by a handler once they have finished their shutdown in the 'dir' direction. Propagates the shutdown process to the next handler in the channel.

## ◆ operator=()

ChannelHandler & Aws::Crt::Io::ChannelHandler::operator= | ( | const ChannelHandler & |  | ) |
| delete

## ◆ ProcessReadMessage()

virtual int Aws::Crt::Io::ChannelHandler::ProcessReadMessage | ( | struct aws_io_message * | message | ) |
| protectedpure virtual

Called by the channel when a message is available for processing in the read direction. It is your responsibility to call aws_mem_release(message->allocator, message); on message when you are finished with it.

Also keep in mind that your slot's internal window has been decremented. You'll want to call aws_channel_slot_increment_read_window() at some point in the future if you want to keep receiving data.

Returns
  AWS_OP_SUCCESS if the message is being processed. If the message cannot be processed raise an error and return AWS_OP_ERR and do NOT release the message, it will be released by the caller.

## ◆ ProcessShutdown()

virtual void Aws::Crt::Io::ChannelHandler::ProcessShutdown | ( | ChannelDirection | dir,
|  | int | errorCode,
|  | bool | freeScarceResourcesImmediately
| ) |  |
| protectedpure virtual

The channel calls shutdown on all handlers twice, once to shut down reading, and once to shut down writing. Shutdown always begins with the left-most handler, and proceeds to the right with dir set to ChannelDirection::Read. Then shutdown is called on handlers from right to left with dir set to ChannelDirection::Write.

The shutdown process does not need to complete immediately and may rely on scheduled tasks. The handler MUST call OnShutdownComplete() when it is finished, which propagates shutdown to the next handler. If 'freeScarceResourcesImmediately' is true, then resources vulnerable to denial-of-service attacks (such as sockets and file handles) must be closed immediately before the shutdown process complete.

## ◆ ProcessWriteMessage()

virtual int Aws::Crt::Io::ChannelHandler::ProcessWriteMessage | ( | struct aws_io_message * | message | ) |
| protectedpure virtual

Called by the channel when a message is available for processing in the write direction. It is your responsibility to call aws_mem_release(message->allocator, message); on message when you are finished with it.

Returns
  AWS_OP_SUCCESS if the message is being processed. If the message cannot be processed raise an error and return AWS_OP_ERR and do NOT release the message, it will be released by the caller.

## ◆ ResetStatistics()

virtual void Aws::Crt::Io::ChannelHandler::ResetStatistics | ( |  | ) |
| inlineprotectedvirtual

Directs the channel handler to reset all of the internal statistics it tracks about itself.

## ◆ ScheduleTask() [1/2]

void Aws::Crt::Io::ChannelHandler::ScheduleTask | ( | std::function< void(TaskStatus)> && | task | ) |

Schedule a task to run on the next "tick" of the event loop. If the channel is completely shut down, the task will run with the 'Canceled' status.

## ◆ ScheduleTask() [2/2]

void Aws::Crt::Io::ChannelHandler::ScheduleTask | ( | std::function< void(TaskStatus)> && | task,
|  | std::chrono::nanoseconds | run_in
| ) |  |

Schedule a task to run after a desired length of time has passed. The task will run with the 'Canceled' status if the channel completes shutdown before that length of time elapses.

## ◆ SendMessage()

bool Aws::Crt::Io::ChannelHandler::SendMessage | ( | struct aws_io_message * | message,
|  | ChannelDirection | direction
| ) |  |
| protected

Send a message in the read or write direction. Returns true if message successfully sent. If false is returned, you must release the message yourself.

## ◆ ShutDownChannel()

void Aws::Crt::Io::ChannelHandler::ShutDownChannel | ( | int | errorCode | ) |

Initiate a shutdown of the handler's channel.

If the channel is already shutting down, this call has no effect.

## ◆ UpstreamMessageOverhead()

size_t Aws::Crt::Io::ChannelHandler::UpstreamMessageOverhead | ( |  | ) | const
| protected

Fetches the current overhead of upstream handlers. This provides a hint to avoid fragmentation if you care.

## Member Data Documentation

## ◆ m_allocator

Allocator* Aws::Crt::Io::ChannelHandler::m_allocator
| protected

## ◆ m_handler

struct aws_channel_handler Aws::Crt::Io::ChannelHandler::m_handler
| protected

## ◆ s_GatherStatistics

void Aws::Crt::Io::ChannelHandler::s_GatherStatistics

## ◆ s_IncrementReadWindow

int Aws::Crt::Io::ChannelHandler::s_IncrementReadWindow

## ◆ s_InitialWindowSize

size_t Aws::Crt::Io::ChannelHandler::s_InitialWindowSize

## ◆ s_MessageOverhead

size_t Aws::Crt::Io::ChannelHandler::s_MessageOverhead

## ◆ s_ProcessReadMessage

int Aws::Crt::Io::ChannelHandler::s_ProcessReadMessage

## ◆ s_ProcessShutdown

int Aws::Crt::Io::ChannelHandler::s_ProcessShutdown

## ◆ s_ProcessWriteMessage

int Aws::Crt::Io::ChannelHandler::s_ProcessWriteMessage

## ◆ s_ResetStatistics

void Aws::Crt::Io::ChannelHandler::s_ResetStatistics

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

- crt/aws-crt-cpp/include/aws/crt/io/ChannelHandler.h
- crt/aws-crt-cpp/source/io/ChannelHandler.cpp