Complete batch receive other feature of C client

[shibd]

Master Issue: #252

Motivation

Complete batch receive other feature.

Modifications

• Add batch receive policy.
• Implement asynchronous batch receive.

Verifying this change

• Add batch receive async test.

Documentation

• doc-required
  (Your PR needs to update docs and you will update later)

• doc-not-needed
  (Please explain why)

• doc
  (Your PR contains doc changes)

• doc-complete
  (Docs have been already added)

[BewareMyPower]

Suggested change

	* 1. When it's callback call result is `ResultOk`, `*msg` will point to the memory that
	* is allocated internally. You have to call `pulsar_messages_free` to free it.
	* 2. If callback call result is not `ResultOk`, `*msg` will is nullptr.
	* 1. When the result in the callback is `ResultOk`, `*msg` will point to the memory that
	* is allocated internally. You have to call `pulsar_messages_free` to free it.
	* 2. If the result in the callback is not `ResultOk`, `*msg` will be nullptr.

Fix wrong semantic.

And I think this description is wrong. Because the asynchronous API does not have a msg parameter.

[shibd]

This msg mean callback result msg.

[BewareMyPower]

Then msg is pulsar_messages_t*, not pulsar_messages_t**. We should not use *msg here, because now *msg is pulsar_messages_t, which is a struct and could never be nullptr.

[shibd]

because now *msg is pulsar_messages_t, which is a struct and could never be nullptr.

Isn't *msg a pointer representing pulsar_messages_t object?

[BewareMyPower]

No. Let's review the basic knowledge of C first. Given the pointer int* p, *p is the int object that p points to, while p is the pointer that points to an int.

Then, see the synchronous batch receive method:

PULSAR_PUBLIC pulsar_result pulsar_consumer_batch_receive(pulsar_consumer_t *consumer,
                                                          pulsar_messages_t **msgs);

• msgs is a pointer that points to pulsar_messages_t*, which is a pointer that points to a pulsar_messages_t object.
• *msgs is a pointer that msgs points to, i.e. *msgs is the pointer that points to a pulsar_messages_t object.

Let's see the callback in this PR.

typedef void (*pulsar_batch_receive_callback)(pulsar_result result, pulsar_messages_t *msg, void *ctx);

• msg is a pointer that points to a pulsar_messages_t object.
• *msg is the pulsar_messages_t object that msg points to.

[shibd]

I see.

Isn't *msg a pointer representing pulsar_messages_t object?

This statement is wrong and should be: msg is a pointer representing pulsar_messages_t object.

Let's get back to the discussion. The flow code.

            pulsar_messages_t *msgs = nullptr;
            if (result == pulsar::ResultOk) {
                msgs = new pulsar_messages_t;
                // set data.
            }
            callback((pulsar_result)result, msgs, ctx);

• msgs is a pointer that points to a pulsar_messages_t object.
• *msgs is the pulsar_messages_t object that msg points to.

So, I pass a msgs is not *msgs. What I passed in was a pointer, right? I can pass in a nullptr.

I need change note

- * 1. When the result in the callback is `ResultOk`, `*msg` in the callback will point to the memory that
- * is allocated internally. You have to call `pulsar_messages_free` to free it.
- * 2. If the result in the callback is not `ResultOk`, `*msg` in the callback will is nullptr.

+ * 1. When the result in the callback is `ResultOk`, `msg` in the callback will point to the memory that
+ * is allocated internally. You have to call `pulsar_messages_free` to free it.
+ * 2. If the result in the callback is not `ResultOk`, `msg` in the callback will is nullptr.

[BewareMyPower]

The changes you made is correct. BTW, will is -> will be.