• Overview
• Asynchronous Completion Token (ACT) pattern [POSA2]
  • Background
  • Solution
  • Structure
    • Class diagram
    • Dynamic
• Simplified version of Implementation
  • Design Choices
  • Component Mapping
  • Framework Layer
  • Application Layer
  • Class diagram
  • Sequence diagram
  • Directory and file structure

Overview

This post covers the following topics:

• The Asynchronous Completion Token pattern for efficiently managing state in asynchronous operations.
• A simplified implementation inspired by the Adaptive Communication Environment (ACE). The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Asynchronous Completion Token (ACT) pattern [POSA2]

The Asynchronous Completion Token (ACT) also known as Active Demultiplexing, lets an application efficiently demultiplex and process the results of asynchronous operations that the application initiated.

Background

In a multi-threaded system, a client application may invoke operations on services and later receive the results asynchronously via completion events. When a completion event arrives, the client is responsible for demultiplexing it to the correct completion handler so the result can be processed.

To handle this efficiently, three factors matter:

• No direct dependency on client state: The service should not need to understand the client’s original context (and often cannot, because the client continues doing other work after initiating the operation).
• Low communication overhead: Avoid extra round trips or side channels just to figure out how the client should process a completion.
• Fast demultiplexing on completion: When the completion event arrives, the client should be able to quickly route it to the correct handler.

Solution

Whenever a client (the initiator) invokes an asynchronous operation on a service, it sends extra information describing how to handle the service’s response. When the operation completes, that information is returned unchanged, enabling the initiator to demultiplex and process the response efficiently.

In Detail:

1. A client creates an Asynchronous Completion Token (ACT) when it invokes an asynchronous operation on a service.
   The ACT contains information that uniquely identifies the completion handler responsible for processing the operation’s response.
2. The ACT is passed to the service along with the operation request.
3. The service keeps the ACT without modifying it.
4. When the operation completes, the service responds to the initiator and includes the original ACT.
5. The initiator uses the ACT to identify the correct completion handler and process the response.

Structure

The Asynchronous Completion Token pattern has four participants:

• Service: Provides functionality and processes requests asynchronously.
• Initiator: Invokes operations on a service asynchronously and demultiplexes the service response to the appropriate handler.
• Completion Handler: A function or object that processes the result of a completed asynchronous operation.
• Asynchronous Completion Token (ACT): Contains information that identifies an initiator’s completion handler. It is passed to the service when the initiator requests an asynchronous operation and is returned unchanged when the operation completes, enabling efficient demultiplexing.

Class diagram

Dynamic

Simplified version of Implementation

Design Choices

This version keeps the core architectural ideas from ACE while intentionally skipping production-level complexity. For example, unlike the full ACE implementation which applied Factory and Bridge design patterns to support multiple platforms, this version supports only the POSIX platform and omits all Factory-related structures.

The participants of ACT in this post are implemented as part of a simplified Proactor framework, which is covered in Proactor framework.

The following framework is used as infrastructure for this implementation:

• Reactor framework

The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Component Mapping

To implement this pattern, I mapped the ACT pattern components to the following C++ classes and associated OS kernel services:

Framework Layer

The core components of ACT in the Proactor framework are:

• Handler: An abstract base class for application-defined completion event handlers. It defines virtual methods like handleReadStream and handleWriteStream to process operation completions.
• ServiceHandler: Extends Handler to support connection initialization (open).
• AsynchResult: Represents the result of an asynchronous operation. It contains the status, bytes transferred, and acts as a carrier for the completion callback to the Handler.
• AsynchReadStream / AsynchWriteStream: Factory classes used by applications to initiate asynchronous read and write operations. They register each request with the Proactor.

Application Layer

The example application demonstrates a hybrid approach where:

• Acceptor: Uses the Reactor pattern to synchronously listen for and accept new TCP connections. Upon acceptance, it creates a ServerEventHandler and hands over the new socket to the Proactor framework.
• ServerEventHandler: A concrete ServiceHandler that manages the lifecycle of a client connection. It initiates asynchronous reads and writes using AsynchReadStream and AsynchWriteStream.

Class diagram

The following diagram illustrates the relationship between the participants of the Asynchronous Completion Token pattern and the application classes. This diagram focuses on the classes involved in transporting the Asynchronous Completion Token.

Sequence diagram

The sequence below illustrates the lifecycle of the ACT: from passing it during initiation to retrieving it during completion.

Directory and file structure

Related source files:

├── applications
│   ├── example_proactor
│   │   ├── Acceptor.cpp
│   │   ├── Acceptor.hpp
│   │   ├── MainClient.cpp
│   │   ├── MainServer.cpp
│   │   ├── ServerEventHandler.cpp
│   │   └── ServerEventHandler.hpp
├── framework
│   ├── proactor
│   │   └── 1_0
│   │       ├── AsynchPseudoTask.cpp
│   │       ├── AsynchPseudoTask.hpp
│   │       ├── AsynchReadStream.cpp
│   │       ├── AsynchReadStream.hpp
│   │       ├── AsynchResult.cpp
│   │       ├── AsynchResult.hpp
│   │       ├── AsynchWriteStream.cpp
│   │       ├── AsynchWriteStream.hpp
│   │       ├── Handler.cpp
│   │       ├── Handler.hpp
│   │       ├── NotifyPipeManager.cpp
│   │       ├── NotifyPipeManager.hpp
│   │       ├── Proactor.cpp
│   │       ├── Proactor.hpp
│   │       ├── ServiceHandler.cpp
│   │       └── ServiceHandler.hpp

• Overview
• Proactor pattern [POSA2]
  • Background
  • Solution
  • Structure
    • Class diagram
    • Dynamic
• Simplified version of Implementation
  • Design Choices
  • Component Mapping
  • Framework Layer
  • Application Layer
  • Class diagram
  • Sequence diagram
  • Directory and file structure

Overview

This post covers the following topics:

• The Proactor pattern for demultiplexing and dispatching events triggered by asynchronous I/O completion.
• A simplified implementation inspired by the Adaptive Communication Environment (ACE). The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Proactor pattern [POSA2]

The Proactor pattern provides an event-driven framework for efficiently handling the initiation of asynchronous operations—which are potentially long-duration—and processing their completion. It offers the performance benefits of concurrency without the complexity downsides often associated with concurrent application design.

Background

The performance of event-driven applications, particularly server applications in distributed systems, can be improved when requests are processed asynchronously instead of using synchronous I/O APIs that block the thread. When processing requests asynchronously, the triggered completion event must be demultiplexed and dispatched to the appropriate component for handling.

To make this approach effective, the following requirements must be met:

• Process multiple completion events in parallel without allowing long-duration processes to block others.
• Maximize throughput by avoiding unnecessary context switching, synchronization overhead, and data movement across CPUs.
• Allow new or improved services to integrate with existing event demultiplexing/dispatching mechanisms with minimal effort.
• Keep application code largely insulated from multi-threading and synchronization complexity.

Solution

• Split the application into two parts:
  • Long duration operation: Executes the long-duration operation asynchronously.
  • Completion handlers: Processes the result of the operation when completed.
• Integrate demultiplexing of the completion event with dispatching events to the corresponding component’s completion event handler.
• Decouple demultiplexing and dispatching operations from the application-specific completion handling implementation.

Structure

The Proactor pattern consists of the following participants:

• Handle: Identifies entities such as network connections or open files. It is provided by the Operating System.
• Asynchronous Operations: Operations used by the application. These are typically long-duration operations, such as reading/writing data asynchronously via a socket.
• Completion Handler: An interface that provides a completion method hook associated with an asynchronous operation. The application implements a concrete handler to define application-specific completion logic.
• Concrete Completion Handlers: Specializes the Completion Handler.
• Asynchronous Operation Processor: Invokes asynchronous operations, which are often provided by the OS kernel. Upon operation completion, a completion event is triggered and dispatched to the corresponding completion handler.
• Completion Event Queue: The completion event is inserted into this queue and waits until it is demultiplexed and dispatched to the corresponding completion handler.
• Asynchronous Event Demultiplexer: Waits for completed events to be inserted into the completion event queue, then returns them to the caller and removes them from the queue.
• Proactor: Provides an event loop for waiting and fetching events from the asynchronous event demultiplexer. Once a completion event is fetched, it dispatches the event to the corresponding completion handler’s event hook method.
• Initiator: An entity within the application that invokes asynchronous operations and often acts as a completion handler.

Class diagram

Dynamic

Simplified version of Implementation

Design Choices

This version keeps the core architectural ideas from ACE while intentionally skipping production-level complexity. For example, unlike the full ACE implementation which applied Factory and Bridge design patterns to support multiple platforms, this version supports only the POSIX platform and omits all Factory-related structures.

The following frameworks are used as infrastructure for this implementation:

• Reactor framework

The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Component Mapping

To implement this pattern, I mapped the Proactor pattern components to the following C++ classes and associated OS kernel services:

Framework Layer

The Core components of the Proactor framework are:

• Proactor: The singleton component that manages the event loop (proactorRunEventLoop). It processes asynchronous operations, handles completion events, and dispatches them to the appropriate handlers.
• Handler: An abstract base class for application-defined event handlers. It defines virtual methods like handleReadStream and handleWriteStream to process operation completions.
• ServiceHandler: Extends Handler to support connection initialization (open).
• AsynchResult: Represents the result of an asynchronous operation. It contains the status, bytes transferred, and acts as a carrier for the completion callback to the Handler.
• AsynchReadStream / AsynchWriteStream: Factory classes used by applications to initiate asynchronous read and write operations. They register the request with the Proactor.

• Application Layer

The example application demonstrates a hybrid approach ( Reactor along with Proactor) where:

• Acceptor: Uses the Reactor pattern to synchronously listen for and accept new TCP connections. Upon acceptance, it creates a ServerEventHandler and hands over the new socket to the Proactor framework.
• ServerEventHandler: A concrete ServiceHandler that manages the lifecycle of a client connection. It initiates asynchronous reads and writes using AsynchReadStream and AsynchWriteStream.

Class diagram

The following diagram illustrates the relationship between the Proactor framework classes and the application classes.

Sequence diagram

• The sequence below depicts the flow of a new client connection and process of received data

• The sequence below continues from the diagram above, where ServerEventHandler writes response data to the client.

Directory and file structure

Related source files:

├── applications
│   ├── example_proactor
│   │   ├── Acceptor.cpp
│   │   ├── Acceptor.hpp
│   │   ├── MainClient.cpp
│   │   ├── MainServer.cpp
│   │   ├── ServerEventHandler.cpp
│   │   └── ServerEventHandler.hpp
├── framework
│   ├── proactor
│   │   └── 1_0
│   │       ├── AsynchPseudoTask.cpp
│   │       ├── AsynchPseudoTask.hpp
│   │       ├── AsynchReadStream.cpp
│   │       ├── AsynchReadStream.hpp
│   │       ├── AsynchResult.cpp
│   │       ├── AsynchResult.hpp
│   │       ├── AsynchWriteStream.cpp
│   │       ├── AsynchWriteStream.hpp
│   │       ├── Handler.cpp
│   │       ├── Handler.hpp
│   │       ├── NotifyPipeManager.cpp
│   │       ├── NotifyPipeManager.hpp
│   │       ├── Proactor.cpp
│   │       ├── Proactor.hpp
│   │       ├── ServiceHandler.cpp
│   │       └── ServiceHandler.hpp

• Overview
• Active Object pattern [POSA2]
  • Background
  • Solution
  • Structure
    • Class diagram
    • Dynamic
• Simplified version of Implementation
  • Design Choices
  • Component Mapping
  • Framework Layer
  • Application Layer
  • Class diagram
  • Sequence diagram
    • Use Case: client waits synchronously
    • Use Case: Client is triggered by callback asynchronously.
  • Directory and file structure

Overview

This post covers the following topics:

• The Active Object pattern for untangling method execution from method invocation to maintain high concurrency.
• A simplified implementation inspired by the Adaptive Communication Environment (ACE). The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Active Object pattern [POSA2]

The Active Object pattern also known as Concurrent Object, decouples method execution from method invocation to enhance concurrency and simplify synchronized access to objects that reside in different threads.

Background

In a multi-threaded system, objects run concurrently, and we must synchronize access to their methods and data if they are shared and modified by multiple threads. In this case, the following constraints should be considered:

• Processing-intensive methods that are called concurrently on an object must not block the entire process.
• Synchronized access to shared objects should be easy to program.
• Applications should be designed to transparently leverage the parallel processing capabilities available on the hardware/software platform.

Solution

Decouple method invocation on the object from method execution.

• Method invocation should occur on the client’s thread, while its execution should occur in a separate thread where the servant object runs.
• From the client’s point of view, it should be like calling ordinary functions.

In Detail:

• The Proxy provides the API of the active object to be invoked, and the Servant provides the business logic of the active object to be executed.
• The Proxy runs on the client thread, while the Servant runs in a separate thread.

Structure

The Active Object pattern consists of the following six components:

• Proxy: Provides an interface that clients invoke to execute a method of the active object residing in a different thread.
• Method Request Class: Defines an interface for executing methods in the active object. It is subclassed to create concrete method request classes.
• Activation List: The Proxy inserts created concrete method request objects into the activation list. These requests are then dequeued and executed by the thread where the active object resides.
• Scheduler: Runs in the active object’s thread. It dequeues the queued method requests from the activation list and executes them.
• Servant: Defines the behavior and state modeled by an active object. The methods implemented by the servant correspond to the interface provided by the proxy. Its methods are executed by the scheduler in the thread where the scheduler runs.
• Future: The client receives a Future object after invoking the interface. The client obtains the result of the method invocation via the Future once the servant finishes executing the method. The client can retrieve the result data by a synchronous wait (blocked wait) or an asynchronous callback.

Class diagram

Dynamic

Simplified version of Implementation

This simplified Active Object pattern implementation and example application were created to better understand how the pattern works and how it is designed.

The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Design Choices

This version keeps the core architectural ideas from ACE while intentionally skipping production-level complexity. For example, unlike the full ACE implementation which applies priority when executing methods in the active list, this version uses a simple FIFO strategy for executing methods.

The following frameworks are used as infrastructure for this implementation:

• Reactor framework
• Task framework

Component Mapping

To implement this pattern, I mapped the standard Active Object components to the following C++ classes:

Framework Layer

• Method Request Class:
  • Implementation: An abstract base class.
  • Interface: Defines a pure virtual call() method that must be implemented by concrete request classes to execute the specific logic.
• ActivationQueue:
  • Implementation: A thread-safe queue wrapper.
  • Logic: Uses standard mutexes and condition variables to safely enqueue requests from the client thread and dequeue them in the scheduler thread.
• Future:
  • Implementation: A template class that holds the result of an asynchronous operation.
  • Logic: Allows the client to retrieve the result via get() (synchronous blocking wait) or attach() (asynchronous callback).

Application Layer

• ActObjServantProxy:
  • Implementation: The client-facing API.
  • Logic: Converts method calls (e.g., requestGetReturnMessage) into MethodRequest objects, enqueues them into the ActObjScheduler, and immediately returns a Future<T> to the client.
• ActObjScheduler:
  • Implementation: Inherits from the Task class to manage the worker thread.
  • Logic: The svc() method runs the event loop, continuously dequeuing requests from the ActivationQueue and invoking their call() method.
• ActObjServant:
  • Implementation: The business logic provider.
  • Logic: Contains the actual implementation of the methods (e.g., RequestGetReturnMessage) which are executed by the Scheduler in its thread.
• RequestGetReturnMessage:
  • Implementation: A concrete implementation of MethodRequest.
  • Logic: In its call() method, it invokes the corresponding method on the ActObjServant, captures the return value, and sets it on the Future to wake up waiting clients.

Class diagram

Sequence diagram

Use Case: client waits synchronously

Use Case: Client is triggered by callback asynchronously.

Directory and file structure

Related source files:

├── applications
│   ├── example_active_object
│   │   ├── ActObjAcceptor.cpp
│   │   ├── ActObjAcceptor.hpp
│   │   ├── ActObjClient.cpp
│   │   ├── ActObjClient.hpp
│   │   ├── ActObjMain.cpp
│   │   ├── ActObjMain.hpp
│   │   ├── ActObjMethodCallback.cpp
│   │   ├── ActObjMethodCallback.hpp
│   │   ├── ActObjMethodRequests.cpp
│   │   ├── ActObjMethodRequests.hpp
│   │   ├── ActObjScheduler.cpp
│   │   ├── ActObjScheduler.hpp
│   │   ├── ActObjServant.cpp
│   │   ├── ActObjServant.hpp
│   │   ├── ActObjServantProxy.cpp
│   │   ├── ActObjServantProxy.hpp
│   │   ├── MainClient.cpp
│   │   └── MainServer.cpp
├── framework
│   ├── active_object
│   │   └── 1_0
│   │       ├── ActivationQueue.cpp
│   │       ├── ActivationQueue.hpp
│   │       ├── Future.cpp
│   │       ├── Future.hpp
│   │       ├── MethodRequest.cpp
│   │       └── MethodRequest.hpp
│   └── task
│       └── 1_0
│           ├── Task.cpp
│           └── Task.hpp

• Overview
• Half-Sync/Half-Async pattern [POSA2]
  • Background
  • Solution
  • Structure
• Simplified implementation
  • class diagram
  • sequence diagram
• Example Application using simplified Task framework
  • Server application
    • Accepror
    • AsyncService
    • SyncService
  • class diagram
  • Sequence Diagram
    • Interoperation between Async and Sync service layer
    • Life Cycle of Async/Sync Service component
  • Directory and file structure

Overview

This post covers the following topics:

• The Half-Sync/Half-Async pattern for decoupling asynchronous operations from synchronous processing.
• A simplified implementation inspired by the Adaptive Communication Environment (ACE). The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Half-Sync/Half-Async pattern [POSA2]

The Half-Sync/Half-Async pattern simplifies programming in concurrent systems by decoupling asynchronous and synchronous service processing without reducing performance.

Background

Concurrent software systems are often designed with a mixture of synchronous and asynchronous processing services.

• An asynchronous-processing-based design is efficient for handling time-critical events such as hardware interrupts or software signal events.
• A synchronous-processing-based design, in contrast, simplifies the programming effort.

To achieve both programming simplicity and high performance, we need to combine these two approaches in the software architecture.

Solution

Decompose the system into two layers, a synchronous service layer and an asynchronous service layer, each running in a different thread. Add a message-queue layer between them so that the two layers communicate via the queue.

• The asynchronous service layer acts as a time-critical, low-level layer. It wakes up on events such as hardware interrupts or software signals from the underlying system and forwards the corresponding messages to the synchronous service layer via the message queue.
• The synchronous service layer implements higher-level, long-duration application services such as database queries or file reading/writing on a separate, independent thread.

Structure

This pattern is organized into three layers:

• Asynchronous (or reactive) service layer
• Synchronous service layer
• Message-queue layer between async and sync layers

Simplified implementation

The design pattern is applied to the Task Framework [SH03] of ACE.

The simplified Task framework is implemented to better understand how the pattern works and how it fits into a layered design.

This version keeps the core architectural ideas from ACE while intentionally skipping production-level complexity.

The source code is available at https://github.com/yjung93/study_ACE_design_pattern.

The framework consists of the following components:

• Task class
  • Base class of synchronous services. It embeds a message queue and a worker thread, enabling the concrete class to perform services in the synchronous service layer.
• Message Queue
  • The asynchronous service layer passes messages through this queue to the synchronous service layer.
• Worker Thread
  • The thread on which the synchronous service runs. It wakes up when it receives a message from the asynchronous service layer and performs the synchronous application service.
• Sync service
  • Concrete subclass of Task. It receives messages from the asynchronous service layer and performs synchronous application services.

class diagram

sequence diagram

Example Application using simplified Task framework

Server application

• Demonstration server that waits for client connections, accepts them, and echoes messages received from clients.
• Consists of Acceptor and AsyncService running on the main thread, and SyncService running on a separate thread.

Accepror

• Accepts incoming connections and creates AsyncService and SyncService objects when a connection is established.
• Registers the AsyncService object with the Reactor so it can receive callback events when a message arrives from a client.

AsyncService

• Receives external events from the Reactor and forwards the corresponding messages to SyncService via the message queue.

SyncService

• Concrete subclass of the Task class.
• Processes synchronous services on a separate, independent thread.

class diagram

Sequence Diagram

Interoperation between Async and Sync service layer

Life Cycle of Async/Sync Service component

Directory and file structure

Related source files:

├── applications
│   ├── example_half-sync_half-async
│   │   ├── Acceptor.cpp
│   │   ├── Acceptor.hpp
│   │   ├── AsyncService.cpp
│   │   ├── AsyncService.hpp
│   │   ├── MainClient.cpp
│   │   ├── MainServer.cpp
│   │   ├── SyncService.cpp
│   │   └── SyncService.hpp
├── framework
│   ├── reactor
│   │   └── 1_0
│   │       ├── EventHandler.cpp
│   │       ├── EventHandler.hpp
│   │       ├── Reactor.cpp
│   │       └── Reactor.hpp
│   └── task
│       └── 1_0
│           ├── Task.cpp
│           └── Task.hpp

• Overview
• Simplified Acceptor-Connector framework implementation
  • Structure
  • Event infrastructure layer classes
  • Connection management layer classes
    • ServiceHandler
    • Acceptor
    • Connector
  • Application layer classes
    • Server application
      • AcceptorImpl
      • InputHandler
    • Client application
      • Client
      • ConnectorImpl
      • OutputHandler
      • Dynamics
  • Directory and file structure

Overview

This post covers the following topics:

• The Acceptor-Connector pattern [POSA2] for decoupling connection establishment and initialization from application logic.
• A simplified implementation inspired by the Adaptive Communication Environment (ACE). The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Simplified Acceptor-Connector framework implementation

I built a small, learning-oriented Acceptor-Connector framework to understand how the pattern works and how it fits into a layered design.

This version keeps the core architectural ideas from ACE while intentionally skipping production-level complexity.

The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Structure

The implementation is organized into three layers:

• Event infrastructure layer classes
• Connection management layer classes
• Application layer classes

The relationships between classes in this framework are shown below.

Event infrastructure layer classes

This simplified framework is built on top of a Reactor framework that provides event demultiplexing and dispatching. For details, see the previous post: Reactor Pattern.

Connection management layer classes

This layer provides generic, application-independent connection and initialization services. It consists of:

• ServiceHandler
• Acceptor
• Connector

ServiceHandler

• Defines the interfaces needed by an application service implementation.
• Concrete services typically act as a client, a server, or both in a peer-to-peer system.
• Created by an Acceptor or Connector when a connection is established.
• Provides a hook that the Acceptor/Connector calls to activate the service once the connection is ready.
• Exposes a transport endpoint used by the application service to communicate with its peer. The endpoint type is parameterized (template) so the OS-specific I/O implementation stays separate from application logic.

Acceptor

• Passively establishes a connected transport endpoint.
• Creates and initializes the associated ServiceHandler when a connection is accepted.
• Decouples acceptance/initialization from the ServiceHandler that runs application logic.

Interaction sequence

Connector

• Actively establishes a connected transport endpoint.
• Creates and initializes the associated ServiceHandler when the connection completes.
• Decouples initiation/initialization from the ServiceHandler that runs application logic.
• Supports synchronous and asynchronous connection.

Interaction sequence (synchronous)

Interaction sequence (asynchronous)

Application layer classes

This layer customizes the generic strategies from the infrastructure and connection layers (via subclassing, composition, and/or template instantiation) to create concrete components that establish connections, exchange data, and implement service behavior.

Server application

Demonstration server: waits for client connections, accepts them, and echoes messages received from clients.

AcceptorImpl

• Concrete subclass of Acceptor.
• Plays the acceptor role by deriving from the Acceptor class.

InputHandler

• Concrete subclass of ServiceHandler.
• Handles client I/O and echoes back received messages.

Client application

Demonstration client: sends user-typed messages to the server and displays the responses.

Client

• A facade that composes a Connector and a ServiceHandler.

ConnectorImpl

• Concrete subclass of Connector.
• Plays the connector role by deriving from the Connector class.

OutputHandler

• Concrete subclass of ServiceHandler.
• Forwards user-typed messages to the server and prints replies.

Dynamics

This diagram shows how the client and server components interact to establish connections and run the service logic.

Directory and file structure

Related source files:

├── applications
│   ├── example_acceptor_connector
│   │   ├── AcceptorImpl.cpp
│   │   ├── AcceptorImpl.hpp
│   │   ├── Client.cpp
│   │   ├── Client.hpp
│   │   ├── ConnectorImpl.cpp
│   │   ├── ConnectorImpl.hpp
│   │   ├── InputHandler.cpp
│   │   ├── InputHandler.hpp
│   │   ├── MainClient.cpp
│   │   ├── MainServer.cpp
│   │   ├── OutputHandler.cpp
│   │   └── OutputHandler.hpp
├── framework
│   ├── acceptor_connector
│   │   └── 1_0
│   │       ├── Acceptor.cpp
│   │       ├── Acceptor.hpp
│   │       ├── Config.hpp
│   │       ├── Connector.cpp
│   │       ├── Connector.hpp
│   │       ├── ServiceHandler.cpp
│   │       ├── ServiceHandler.hpp
│   │       ├── SockAcceptor.cpp
│   │       ├── SockAcceptor.hpp
│   │       ├── SockConnector.cpp
│   │       ├── SockConnector.hpp
│   │       ├── SockStream.cpp
│   │       └── SockStream.hpp

• Overview
• Reactor Pattern [POSA2]
  • Background
  • Solution
  • Structure
    • Class Diagram
    • Dynamic
• Simplified Reactor framework implementation
  • Structure
  • Core classes
    • Reactor
    • EventHandler
  • Interaction sequence
  • Example: echo server and client
    • How it works
  • Directory and file structure

Overview

This post covers the following topics:

• The Reactor pattern using a single event loop to demultiplex I/O events and dispatch them to registered handlers.
• A simplified implementation inspired by the Adaptive Communication Environment (ACE), focusing on the essentials rather than production complexity. The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Reactor Pattern [POSA2]

The Reactor pattern is a design pattern for handling service requests delivered concurrently to an application by one or more clients. It efficiently demultiplexes and dispatches events to the appropriate handlers. It provides the following benefits:

• Efficiency: Handles multiple events using a single thread, reducing overhead.
• Scalability: Suitable for systems with many simultaneous connections.
• Maintainability: Promotes modular and decoupled code design.

Background

Event-driven applications in distributed systems, even if originally designed to process service requests synchronously and serially, must often process multiple service requests simultaneously. The multiple concurrent events must be demultiplexed and dispatched to the appropriate application service handlers.

The following forces must be resolved to address this problem:

• To improve scalability and latency, the application should not block the thread when an event is triggered or exclude events from other sources.
• To maximize throughput, context switching, unnecessary synchronization, and data movement among CPUs should be avoided.
• Adding and improving services within the existing event demultiplexing and dispatching system should require minimal effort.
• The application’s implementation should be decoupled from the complexities of multi-threading and synchronization.

Solution

• Synchronously wait for events from different sources.
• Apply a mechanism that demultiplexes and dispatches events to the application services that process them.
• Decouple the demultiplexing and dispatching mechanisms from the application service implementation.

In Detail:

• An application implements a separate event handler for each service.
• Event handlers are registered with the Reactor.
• The Reactor uses a synchronous event demultiplexer to wait for an indication that an event has occurred.
• The event demultiplexer notifies the Reactor when these events occur.
• The Reactor dispatches the event to the associated registered event handler.
• The event handler performs its application service.

Structure

• Handles: Identify event sources such as network connections or open files. These are provided by the operating system.
• Synchronous event demultiplexer: A function that waits for the occurrence of one or more events. Calling this function blocks the thread until an event occurs. The select() system call is a common synchronous event demultiplexer for I/O events, supported by many operating systems.
• Event handler: Specifies an interface composed of one or more hook methods. These methods represent a set of operations that can be used to process application-specific events.
• Concrete event handlers: Specialize the event handler and implement the application’s services.
• Reactor: Provides an interface for applications to register or unregister their event handlers and associated handles. It runs the application’s event loop and waits for event indications on the associated handles using a synchronous demultiplexer. When an event occurs, it dispatches the event to the corresponding event handler registered by the application.

Class Diagram

Dynamic

Simplified Reactor framework implementation

I built a small, learning-oriented framework that retains the core ideas from ACE (initiation dispatcher, event demultiplexing, handler registration) while keeping the code minimal.

The source code is available at https://github.com/yjung93/study_ACE_design_pattern

Structure

At a high level:

• Reactor – runs the event loop, waits for events, dispatches to handlers.
• EventHandler – base class; concrete handlers implement the I/O logic.

Core classes

Reactor

• Maintains a registry of active handlers.
• Uses a synchronous demultiplexer (e.g., select) to wait for activity.
• Dispatches handleInput(fd) on the ready handlers.
• Provides registerHandler() and removeHandler() to manage the registry and lifetime.

EventHandler

• Base interface for application-specific handlers.
• Stores the OS handle/FD and a back-reference to the Reactor.
• Overridable handleInput(fd) method contains the actual I/O logic for each handler.

Interaction sequence

1. Handlers register themselves (or are registered by an acceptor) with the Reactor.
2. The Reactor blocks in select() and wakes when one or more FDs are ready.
3. For each ready FD, the corresponding handler’s handleInput(fd) is invoked.
4. Handlers may read/write, create new handlers (e.g., for new connections), or deregister on close.

Example: echo server and client

For a quick demo, I built a tiny echo server using:

• An Acceptor-like handler for passive opens (creates a per-connection handler).
• A Server handler that reads data and echoes it back.
• A simple client that connects, sends user input, and prints the response.

How it works

• The Acceptor listens for new client connections. When a connection is established, it creates a ServerEventHandler and registers it with the Reactor.
• The Reactor monitors all registered event handlers using the select() system call and delegates events to their respective handlers.
• The ServerEventHandler processes client messages and echoes them back.

This shows how the Reactor’s single event loop can manage multiple connections cleanly, while each handler stays focused on its own responsibility.

Directory and file structure

Related source files for the Reactor demo:

├── applications
│   ├── example_reactor
│   │   ├── MainClient.cpp
│   │   ├── MainServer.cpp
│   │   ├── ServerEventHandler.cpp
│   │   ├── ServerEventHandler.hpp
│   │   └── Acceptor.cpp / Acceptor.hpp     # minimal acceptor used by the server
├── framework
│   └── v_1_0
│       ├── Reactor.cpp
│       ├── Reactor.hpp
│       ├── EventHandler.cpp
│       └── EventHandler.hpp

[POSA2] Douglas C. Schmidt, Michael Stal, Hans Rohnert, and Frank Buschmann: Pattern-Oriented Software Architecture: Patterns for Concurrent and Networked Objects, Volume 2. Wiley & Sons, New York, 2000.

[SH03] Douglas C. Schmidt, Stephen D. Huston: C++ Network Programming, Volume 2: Systematic Reuse with ACE and Frameworks, Addison-Wesley, 2003 .