> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-core/concepts/transactions.md). # Transactions ## Overview As described in [Message Processing](/rumi-core/concepts/microservice-operation/message-processing.md) and [Cluster Consensus](/rumi-core/concepts/microservice-operation/cluster-consensus.md), the AEP engine uses transactions to ensure state consensus in a service cluster. While a microservice processes messages, the AEP engine prepares and atomically replicates transactions in a manner that ensures the primary instance's store is identically consistent with the store on each of the backup instances in the cluster. ## Transaction Elements What constitutes a transaction is determined by the service consensus model. The followng lists the contents of a transaction: * **State Replicated Microservices** * Inbound message metadata * Service store change log * Outbound messages sent outbound as part of the inbound message processing * **Event Sourced Microservices** * Inbound message metadata * Inbound messages By default, each inbound message starts and terminates a transaction. However, the AEP engine can bundles multiple inbound messages into a single transaction and commit the entire batch as a single atomic unit. This is called *adaptive batching.* ## The Transaction Pipeline When an inbound message enters the engine's event dispatch loop, the message is attached to the current transaction. As the engine routes the message through its handlers, it incrementally updates the [elements](#transaction-elements) of the transaction. On return from the message handler, the engine decides whether to commit the transaction or not. If it does, it * Marks the transaction as complete * Creates a new current transaction * Dispatches the completed transaction for commitment i.e. replication and persistence across the cluster to achieve cluster consensus. Transaction commitment occurs in a **pipelined** manner: while a transaction is being replicated across the cluster, the engine continues to process and commit new inbound messages under subsequent transactions. A transaction in the process of being committed is called an **inflight** transaction and the set of all such transactions is called the **transaction pipeline**. ## Adaptive Batching By default, an AEP engine processes each inbound message in a single transaction. It is possible to configure the engine to batch up the processing of several inbound messages into a single transaction. This feature us called **adaptive batching**. Adaptive batching can significantly improve throughput. However, this is generally at the cost of increased latency of outbound messages since the outbound messages for the first message processed in a transaction won't be sent until the last message in the transaction has been processed and the transaction dispatched for commit. The batching behavior is adaptive in nature because the engine commits a transaction automatically when either a configured adaptive batch ceiling is reached or the engine detects there are no more messages immediately available to process. In other words, if there are messages arriving significantly fast that they can be added to the current transaction with no additional weight, then the batch size of the transaction will grow to the configured batch ceiling. However, if there is a slight lull in the inbound traffic pattern that would cause the engine to have to wait for the next message to fill the batch, then the engine does not wait and will immediately close the batch. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.rumi.systems/rumi-core/concepts/transactions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.