[feat][cpp] Add async receive function to C API

[equanz]

Master Issue: #14452

Motivation

I want to rewrite the pulsar-client-node receive method to rely exclusively on async operations rather than worker threads.
However, an async receive function is not defined currently in C API.

Modifications

• Define pulsar_consumer_receive_async and pulsar_receive_callback to use async receive operation in C API

Verifying this change

• Make sure that the change passes the CI checks.

(Please pick either of the following options)

This change is already covered by existing tests, such as C++ tests.

Does this pull request potentially affect one of the following parts:

If yes was chosen, please highlight the changes

• Dependencies (does it add or upgrade a dependency): (no)
• The public API: (yes)

  • pulsar/pulsar-client-cpp/include/pulsar/c/consumer.h

    Line 36 in 66765af

    typedef void (*pulsar_receive_callback)(pulsar_result result, pulsar_message_t *msg, void *ctx);

  • pulsar/pulsar-client-cpp/include/pulsar/c/consumer.h

    Lines 100 to 108 in 66765af

    	/**
    	* Asynchronously receive a single message.
    	*
    	* This method will initiate the operation and return immediately. The provided callback
    	* will be triggered when the operation is complete.
    	*
    	* @param callback callback that will be triggered when the message is available
    	*/
    	PULSAR_PUBLIC void pulsar_consumer_receive_async(pulsar_consumer_t *consumer, pulsar_receive_callback callback,

• The schema: (no)
• The default values of configurations: (no)
• The wire protocol: (no)
• The rest endpoints: (no)
• The admin cli options: (no)
• Anything that affects deployment: (no)

Documentation

Check the box below or label this PR directly.

Need to update docs?

• doc-not-needed

[tisonkun]

cc @BewareMyPower @shibd @RobertIndie

[equanz]

/pulsarbot rerun-failure-checks

[BewareMyPower]

Could you add a basic e2e test for demonstrate it works? I found currently there are nearly no C API related tests. But for new APIs, we should add some tests.

[equanz]

@BewareMyPower

Could you add a basic e2e test for demonstrate it works?

Okay. I'll address it.

[BewareMyPower]

I think we should release the received_msg after the callback is done. It's better to use pure C semantics here, i.e. use C functions instead of lambda, and do not use pulsar::Promise, we should define a C struct and pass it to ctx.

[equanz]

I'll modify it.

However, I also use pulsar::Promise to wait for the callback completion in the test thread.
To achieve this process, I'll use std::future instead of conditional wait, etc.