Skip to content

[C++] Update public API and simplify client lifecycle state machine - #1300

Merged
lizhimins merged 1 commit into
apache:masterfrom
lizhimins:cpp-api-lifecycle-refactor
Jul 10, 2026
Merged

lizhimins merged 1 commit into
apache:masterfrom
lizhimins:cpp-api-lifecycle-refactor

Conversation

@lizhimins

Copy link
Copy Markdown
Member

Summary

Update the C++ client public API for consistency and simplify the client lifecycle state machine from 5 states to 3 states (CREATED β†’ STARTED β†’ STOPPED).

Changes

Public API

  • SendCallback: change signature from const SendReceipt& to SendReceipt&& (move semantics)
  • Producer / FifoProducer: sink parameter pattern for Message
  • PushConsumer: add noexcept to shutdown(), swallow exceptions in destructor
  • SimpleConsumer: noexcept shutdown, API updates

Lifecycle State Machine

  • Simplify from 5 states to 3: CREATED β†’ STARTED β†’ STOPPED
  • ClientImpl::start() and ClientImpl::shutdown() remain virtual β€” subclasses override with explicit base class calls
  • Each subclass (ProducerImpl, PushConsumerImpl, SimpleConsumerImpl) manages its own state transition with compare_exchange_strong
  • session_map_.clear() added to ClientImpl::shutdown() before client_manager_.reset() to prevent use-after-free

Internal Improvements

  • RpcClientImpl: need_heartbeat_ changed to std::atomic<bool>
  • ReceiveMessageStreamReader: add weak_ptr check before use
  • ClientManagerMock: updated for new API signatures

Testing

  • All 36 unit tests pass
  • Examples verified against real RocketMQ server (producer 10/10, async 5/5, FIFO 5/5, simple consumer, push consumer)

@RockteMQ-AI RockteMQ-AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review by github-manager-bot

Summary

This PR updates the C++ client public API for consistency (move semantics, sink parameters, noexcept) and simplifies the client lifecycle state machine from 5 states to 3 (CREATED β†’ STARTED β†’ STOPPED).

Findings

  • [Info] cpp/source/rocketmq/ClientImpl.cpp β€” The state machine simplification is well-structured. The shutdown_requested_ flag checked at the end of start() correctly handles the race where shutdown is requested during startup. Good defensive design.

  • [Info] cpp/source/rocketmq/FifoProducerPartition.cpp β€” The lock-scope reduction in trySend() (releasing messages_mtx_ before calling producer_->send()) correctly prevents the deadlock scenario described in the comment. The exception handler that invokes the callback with operation_canceled is appropriate.

  • [Warning] cpp/source/rocketmq/ClientImpl.cpp:~110 β€” The comment acknowledges that if an exception is thrown during resource allocation in start(), partially-allocated resources may leak since shutdown() becomes a no-op when state is still CREATED. Consider adding RAII guards or a cleanup path for the STARTED β†’ resource allocation failure case to prevent leaks in error scenarios.

  • [Info] cpp/source/client/ReceiveMessageStreamReader.cpp β€” The weak_ptr check before use is a good fix preventing use-after-free when ClientManager has been destructed.

  • [Info] cpp/source/client/RpcClientImpl.cpp β€” Separating the null check from the channel state check in ok() is a clean defensive improvement.

  • [Info] cpp/include/rocketmq/SendCallback.h β€” Changing from const SendReceipt& to SendReceipt&& (move semantics) is correct since SendReceipt contains a MessageConstSharedPtr that can be moved efficiently.

Suggestions

  1. Resource leak on start() failure: The acknowledged leak in ClientImpl::start() when exceptions occur during resource allocation could be addressed with a scope guard pattern:

    // In start(), after resource allocation begins:
    auto cleanup_on_failure = absl::MakeCleanup([&] {
      if (state_.load(std::memory_order_relaxed) == State::CREATED) {
        // Partial cleanup for resources allocated so far
      }
    });
  2. Consider documenting the noexcept contract: Since several public API methods now swallow exceptions internally (e.g., PushConsumer::subscribe, SimpleConsumer::asyncReceive), consider adding @note in the header documentation explaining that exceptions are caught and logged, so callers should check error codes rather than expecting exceptions.

Cross-repo Note

This PR modifies the C++ client API (SendCallback signature change). If the Java/Go/C++ clients share a common gRPC protocol definition, ensure the protocol layer is unaffected. The changes here are purely client-side API ergonomics and should not require proxy-side changes.


Automated review by github-manager-bot

@lizhimins
lizhimins merged commit 41b65fa into apache:master Jul 10, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants