Android-style message handler for event-driven programming. More...

#include <Handler.h>

Inheritance diagram for swt::Handler:

Collaboration diagram for swt::Handler:

Public Member Functions
	Handler ()
	Default constructor - not associated with any looper.

	Handler (std::shared_ptr< SLLooper > &looper)
	Constructor with looper association.

virtual	~Handler ()
	Virtual destructor.

std::shared_ptr< Message >	obtainMessage ()
	Obtain a new empty message.

std::shared_ptr< Message >	obtainMessage (int32_t what)
	Obtain a message with type code.

std::shared_ptr< Message >	obtainMessage (int32_t what, int32_t arg1)
	Obtain a message with type code and argument.

std::shared_ptr< Message >	obtainMessage (int32_t what, void *obj)
	Obtain a message with type code and object pointer.

std::shared_ptr< Message >	obtainMessage (int32_t what, int32_t arg1, int32_t arg2)
	Obtain a message with type code and two arguments.

std::shared_ptr< Message >	obtainMessage (int32_t what, int32_t arg1, int32_t arg2, void *obj)
	Obtain a message with type code, two arguments, and object pointer.

std::shared_ptr< Message >	obtainMessage (int32_t what, int32_t arg1, int32_t arg2, int32_t arg3)
	Obtain a message with type code and three arguments.

std::shared_ptr< Message >	obtainMessage (int32_t what, std::shared_ptr< RefBase > spRef)
	Obtain a message with type code and shared pointer reference.

bool	sendMessage (const std::shared_ptr< Message > &message)
	Send message for immediate processing.

bool	sendMessageDelayed (const std::shared_ptr< Message > &message, int64_t delayMs)
	Send message with delay.

bool	sendMessageAtTime (const std::shared_ptr< Message > &message, int64_t whenUs)
	Send message at specific time.

bool	hasMessages (int32_t what)
	Check if message with type code exists in queue.

bool	removeMessages (int32_t what)
	Remove messages with type code from queue.

bool	removeMessages (int32_t what, void *obj)
	Remove messages with type code and object pointer from queue.

void	dispatchMessage (const std::shared_ptr< Message > &message)
	Dispatch message to handler (internal use)

int64_t	uptimeMicros ()
	Get current system uptime in microseconds.

virtual void	handleMessage (const std::shared_ptr< Message > &msg)=0
	Override to handle received messages.

Detailed Description

Android-style message handler for event-driven programming.

Handler provides a flexible mechanism for processing messages and events in the context of an event loop (SLLooper). It enables asynchronous communication between threads and decouples message producers from consumers. Each Handler is associated with a specific event loop and message queue (EventQueue).

Key features:

Message creation: Multiple overloads of obtainMessage for flexible message construction
Message sending: Immediate, delayed, and timed message posting
Message management: Query and remove messages by type or object
Custom processing: Override handleMessage() for custom logic
Thread safety: Safe for use from multiple threads

class MyHandler : public Handler {
public:
    void handleMessage(const std::shared_ptr<Message>& msg) override {
        // Custom message processing
    }
};
 
auto looper = std::make_shared<SLLooper>();
auto handler = std::make_shared<MyHandler>(looper);
auto msg = handler->obtainMessage(1, 42, 0);
handler->sendMessage(msg);

See also: Message, SLLooper, EventQueue

Definition at line 45 of file Handler.h.

Constructor & Destructor Documentation

◆ Handler() [1/2]

swt::Handler::Handler ( )

Default constructor - not associated with any looper.

◆ Handler() [2/2]

swt::Handler::Handler ( std::shared_ptr< SLLooper > & looper )

Constructor with looper association.

Constructor - associates handler with event loop.

Parameters

looper	Shared pointer to SLLooper for event loop context
looper	SLLooper instance for message queue access

Initializes the handler with a reference to the event loop's message queue. The handler will post messages to this queue and receive callbacks when messages are processed in the event loop thread.

Key initialization:

EventQueue access: Gets queue from looper for message operations
Looper reference: Maintains weak reference to prevent circular deps
Thread context: Handler callbacks execute in looper's thread context

Note: Handler must be created as shared_ptr due to enable_shared_from_this; All message operations will use this looper's event queue

Definition at line 42 of file Handler.cpp.

◆ ~Handler()

swt::Handler::~Handler ( )

virtual

Virtual destructor.

Destructor - cleanup handler resources.

Performs cleanup of handler resources. In a complete implementation, this would remove any pending messages associated with this handler from the event queue.

Note: Currently no explicit cleanup needed due to shared_ptr management

Definition at line 57 of file Handler.cpp.

Member Function Documentation

◆ dispatchMessage()

void swt::Handler::dispatchMessage ( const std::shared_ptr< Message > & message )

Dispatch message to handler (internal use)

Dispatch message to handler for processing.

Parameters

message Message to dispatch

See also: handleMessage()

Parameters

message Message to process

Called by the event loop when a message targeted to this handler is ready for processing. Delegates to the virtual handleMessage() method for actual message handling.

This method provides an extension point for message preprocessing or logging before actual message handling occurs.

Note: Called in event loop thread context; Override handleMessage() for custom message processing

Definition at line 349 of file Handler.cpp.

References handleMessage().

Here is the call graph for this function:

◆ handleMessage()

virtual void swt::Handler::handleMessage ( const std::shared_ptr< Message > & msg )

pure virtual

Override to handle received messages.

Parameters

msg	Message to process

See also: Message

Referenced by dispatchMessage().

Here is the caller graph for this function:

◆ hasMessages()

bool swt::Handler::hasMessages ( int32_t what )

Check if message with type code exists in queue.

Check if handler has pending messages of specific type.

Parameters

what	Message type code

Returns: true if message exists

Parameters

what	Message type identifier to check

Returns: true if messages of this type are pending

Queries the event queue for pending messages with the specified 'what' value that are targeted to this handler.

if (handler->hasMessages(UPDATE_UI)) {
    // UI update already pending, skip duplicate
}

Note: Only checks messages targeted to this handler; Useful for avoiding duplicate message posting

Definition at line 291 of file Handler.cpp.

◆ obtainMessage() [1/8]

std::shared_ptr< Message > swt::Handler::obtainMessage ( )

Obtain a new empty message.

Create a basic message with this handler as target.

Returns: Shared pointer to new Message

See also: Message

Returns: std::shared_ptr<Message> New message object

Creates a message that will be delivered to this handler's handleMessage() when processed by the event loop. This is the most basic message creation.

auto message = handler->obtainMessage();

handler->sendMessage(message);

Note: Uses shared_from_this() - handler must be created as shared_ptr

See also: Message::obtain(), sendMessage()

Definition at line 80 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [2/8]

std::shared_ptr< Message > swt::Handler::obtainMessage ( int32_t what )

Obtain a message with type code.

Create message with 'what' identifier.

Parameters

what	Message type code

Returns: Shared pointer to new Message

See also: Message

Parameters

what	Message type identifier

Returns: std::shared_ptr<Message> New message object

Creates a message with a specific type identifier. The 'what' field allows handlers to distinguish between different message types.

enum MessageTypes { UPDATE_UI = 1, PROCESS_DATA = 2 };

auto message = handler->obtainMessage(UPDATE_UI);

Definition at line 98 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [3/8]

std::shared_ptr< Message > swt::Handler::obtainMessage	(	int32_t	what,
		int32_t	arg1
	)

Obtain a message with type code and argument.

Create message with 'what' and first argument.

Parameters

what	Message type code
arg1	First argument

Returns: Shared pointer to new Message

Parameters

what	Message type identifier
arg1	First integer argument

Returns: std::shared_ptr<Message> New message object

Creates a message with type and one integer argument. Useful for simple parameter passing in message-based communication.

Definition at line 112 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [4/8]

std::shared_ptr< Message > swt::Handler::obtainMessage	(	int32_t	what,
		int32_t	arg1,
		int32_t	arg2
	)

Obtain a message with type code and two arguments.

Create message with 'what' and two arguments.

Parameters

what	Message type code
arg1	First argument
arg2	Second argument

Returns: Shared pointer to new Message

Parameters

what	Message type identifier
arg1	First integer argument
arg2	Second integer argument

Returns: std::shared_ptr<Message> New message object

Creates a message with type and two integer arguments. Common pattern for coordinate pairs, dimensions, or simple parameter combinations.

// Send window resize message

auto message = handler->obtainMessage(RESIZE_WINDOW, width, height);

Definition at line 149 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [5/8]

std::shared_ptr< Message > swt::Handler::obtainMessage	(	int32_t	what,
		int32_t	arg1,
		int32_t	arg2,
		int32_t	arg3
	)

Obtain a message with type code and three arguments.

Create message with 'what' and three arguments.

Parameters

what	Message type code
arg1	First argument
arg2	Second argument
arg3	Third argument

Returns: Shared pointer to new Message

Parameters

what	Message type identifier
arg1	First integer argument
arg2	Second integer argument
arg3	Third integer argument

Returns: std::shared_ptr<Message> New message object

Extended message creation with three integer arguments for scenarios requiring additional parameter data.

Definition at line 181 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [6/8]

std::shared_ptr< Message > swt::Handler::obtainMessage	(	int32_t	what,
		int32_t	arg1,
		int32_t	arg2,
		void *	obj
	)

Obtain a message with type code, two arguments, and object pointer.

Create message with 'what', two arguments, and object.

Parameters

what	Message type code
arg1	First argument
arg2	Second argument
obj	Object pointer

Returns: Shared pointer to new Message

Parameters

what	Message type identifier
arg1	First integer argument
arg2	Second integer argument
obj	Pointer to arbitrary object data

Returns: std::shared_ptr<Message> New message object

Creates a message with full parameter set: type, two integers, and object. Most comprehensive message creation method for complex scenarios.

Definition at line 165 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [7/8]

std::shared_ptr< Message > swt::Handler::obtainMessage	(	int32_t	what,
		std::shared_ptr< RefBase >	spRef
	)

Obtain a message with type code and shared pointer reference.

Create message with 'what' and shared reference object.

Parameters

what	Message type code
spRef	Shared pointer reference

Returns: Shared pointer to new Message

Parameters

what	Message type identifier
spRef	Shared pointer to reference-counted object

Returns: std::shared_ptr<Message> New message object

Creates a message with a shared reference object. Preferred over raw pointers for automatic lifetime management and memory safety.

auto data = std::make_shared<MyData>();

auto message = handler->obtainMessage(PROCESS_DATA, data);

Note: Shared pointer ensures object lifetime during message processing

Definition at line 202 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ obtainMessage() [8/8]

std::shared_ptr< Message > swt::Handler::obtainMessage	(	int32_t	what,
		void *	obj
	)

Obtain a message with type code and object pointer.

Create message with 'what' and object pointer.

Parameters

what	Message type code
obj	Object pointer

Returns: Shared pointer to new Message

Parameters

what	Message type identifier
obj	Pointer to arbitrary object data

Returns: std::shared_ptr<Message> New message object

Creates a message with type and object pointer. The object lifetime must be managed carefully to ensure it remains valid when message is processed.

Warning: Object pointer lifetime must exceed message processing time

Definition at line 129 of file Handler.cpp.

References swt::Message::obtain().

Here is the call graph for this function:

◆ removeMessages() [1/2]

bool swt::Handler::removeMessages ( int32_t what )

Remove messages with type code from queue.

Remove pending messages of specific type.

Parameters

what	Message type code

Returns: true if any messages were removed

Parameters

what	Message type identifier to remove

Returns: true if messages were removed

Removes all pending messages of the specified type that are targeted to this handler from the event queue.

Note: Currently not implemented - returns false

Todo:: Implement message removal functionality

Definition at line 307 of file Handler.cpp.

◆ removeMessages() [2/2]

bool swt::Handler::removeMessages	(	int32_t	what,
		void *	obj
	)

Remove messages with type code and object pointer from queue.

Remove pending messages of specific type and object.

Parameters

what	Message type code
obj	Object pointer

Returns: true if any messages were removed

Parameters

what	Message type identifier to remove
obj	Object pointer to match for removal

Returns: true if messages were removed

Removes pending messages that match both the 'what' type and object pointer, providing more selective message removal.

Note: Currently not implemented - returns false

Todo:: Implement selective message removal functionality

Definition at line 326 of file Handler.cpp.

◆ sendMessage()

bool swt::Handler::sendMessage ( const std::shared_ptr< Message > & message )

Send message for immediate processing.

Send message immediately to event queue.

Parameters

message Message to send

Returns: true if message was successfully sent

See also: Message

Parameters

message Message to send

Returns: true if message was successfully queued

Posts message to the event queue for immediate processing. The message will be processed as soon as the event loop reaches it in the queue.

auto message = handler->obtainMessage(UPDATE_STATUS);
if (!handler->sendMessage(message)) {
    // Handle queue failure
}

Note: Message processed in event loop thread context; Returns immediately - message processed asynchronously

Definition at line 227 of file Handler.cpp.

References sendMessageAtTime(), and uptimeMicros().

Here is the call graph for this function:

◆ sendMessageAtTime()

bool swt::Handler::sendMessageAtTime	(	const std::shared_ptr< Message > &	message,
		int64_t	whenUs
	)

Send message at specific time.

Parameters

message	Message to send
whenUs	Absolute time in microseconds

Returns: true if message was successfully scheduled

Parameters

message	Message to send
whenUs	Absolute time in microseconds when to process message

Returns: true if message was successfully queued

Posts message to be processed at a specific absolute time. Uses the internal microsecond timestamp format for precise timing control.

Note: Time specified in microseconds since system start; Lower-level method used by other send methods

Definition at line 267 of file Handler.cpp.

Referenced by sendMessage(), and sendMessageDelayed().

Here is the caller graph for this function:

◆ sendMessageDelayed()

bool swt::Handler::sendMessageDelayed	(	const std::shared_ptr< Message > &	message,
		int64_t	delayMs
	)

Send message with delay.

Parameters

message	Message to send
delayMs	Delay in milliseconds

Returns: true if message was successfully scheduled

Parameters

message	Message to send
delayMs	Delay in milliseconds before processing

Returns: true if message was successfully queued

Posts message to the event queue with a specified delay. The message will be processed after the delay expires.

// Send timeout message after 5 seconds
auto timeoutMsg = handler->obtainMessage(TIMEOUT);
handler->sendMessageDelayed(timeoutMsg, 5000);

Note: Delay measured from current time; Message can be cancelled before processing if needed

Definition at line 250 of file Handler.cpp.

References ms2us, sendMessageAtTime(), and uptimeMicros().

Here is the call graph for this function:

◆ uptimeMicros()

int64_t swt::Handler::uptimeMicros ( )

Get current system uptime in microseconds.

Returns: Current uptime in microseconds; Current uptime in microseconds

Provides monotonic time measurement for message timing and scheduling. Uses steady_clock to avoid issues with system clock adjustments.

Key characteristics:

Monotonic: Always increases, unaffected by system clock changes
Microsecond precision: High resolution for accurate message timing
System uptime: Measures time since system/process start
Thread-safe: std::chrono functions are thread-safe

Used internally for:

Message scheduling timestamps
Delay calculations
Timer management
Performance measurements

Note: Returns steady_clock time, not wall clock time; Microsecond resolution may be limited by system capabilities

Definition at line 382 of file Handler.cpp.

Referenced by sendMessage(), and sendMessageDelayed().

Here is the caller graph for this function:

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

include/Handler.h
src/Handler.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Handler() [1/2]

◆ Handler() [2/2]

◆ ~Handler()

Member Function Documentation

◆ dispatchMessage()

◆ handleMessage()

◆ hasMessages()

◆ obtainMessage() [1/8]

◆ obtainMessage() [2/8]

◆ obtainMessage() [3/8]

◆ obtainMessage() [4/8]

◆ obtainMessage() [5/8]

◆ obtainMessage() [6/8]

◆ obtainMessage() [7/8]

◆ obtainMessage() [8/8]

◆ removeMessages() [1/2]

◆ removeMessages() [2/2]

◆ sendMessage()

◆ sendMessageAtTime()

◆ sendMessageDelayed()

◆ uptimeMicros()