Kafka日记（五）RdKafka文档翻译

RdKafka文档翻译

出于使用 ， 特做简单翻译 ，仅做参考。
https://arnaud-lb.github.io/php-rdkafka/phpdoc/book.rdkafka.html

函数
string rd_kafka_err2str ( integer $err ) 将rdkafka错误代码转换为字符串

integer rd_kafka_errno2err ( integer $errnox ) 将系统errno转换为Kafka错误代码

integer rd_kafka_errno ( void ) 返回系统errno

integer rd_kafka_offset_tail ( integer $cnt ) 返回一个特殊的偏移量值，该值可用于在主题尾部之前开始使用cnt消息

RdKafka\KafkaConsume类
这是高水平消费者，支持自动分区/撤销（pecl rdkafka>=1.0.0,librdkafka>=0.9）

1)public void RdKafka\KafkaConsumer::assign ([ array $topic_partitions = NULL ] )
更新分配集到$topic_partitions,可以通过调用RdKafka\Conf::setDefaultTopicConf()来更改主题的默认配置
$kafkaConsumer->assign([
    new RdKafka\TopicPartition("logs", 0),
    new RdKafka\TopicPartition("logs", 1),
]);

2)public void RdKafka\KafkaConsumer::commit ([ mixed $message_or_offsets = NULL ] )
同步提交偏移，直到提交偏移或提交失败为止。
如果注册了COMMIT_CB回调，那么它将被调用，并包含未来要使用的调用的提交详细信息。
参数
message_or_offsets
When NULL, commit offsets for the current assignment.
When a RdKafka\Message, commit offset for a single topic+partition based on the message.
When an array of RdKafka\TopicPartition, commit offsets for the provided list of partitions.
异常
Errors/Exceptions
Throws RdKafka\Exception on errors.
例子:
// Commit offsets for the current assignment
$kafkaConsumer->commit();

// Commit offsets based on the message's topic, partition, and offset
$kafkaConsumer->commit($message);

// Commit offsets by providing a list of TopicPartition
$kafkaConsumer->commit([
    new RdKafka\TopicPartition($topic, $partition, $offset),
]);

3)public void RdKafka\KafkaConsumer::commitAsync ([ string $message_or_offsets = NULL ] )
异步提交偏移
4)public RdKafka\KafkaConsumer::__construct ( RdKafka\Conf $conf )
参数
conf (RdKafka\Conf)
The conf object must have group.id set to the consumer group to join.
conf对象必须将Group.id设置为要加入的消费者组。
示例：
$conf = new RdKafka\Conf();
$conf->set("group.id", "myGroupID");

$kafkaConsumer = new RdKafka\KafkaConsumer($conf);
5)public RdKafka\Message RdKafka\KafkaConsumer::consume ( string $timeout_ms )
使用消息或获取错误事件，触发回调
将自动调用任何此类排队事件的已注册回调，包括rebalance_cb, event_cb, commit_cb, etc.
参数
timeout_ms (int)  超时时间(milliseconds)
返回值
Returns a RdKafka\Message. On error or timeout, RdKafka\Message::$err is != RD_KAFKA_ERR_NO_ERROR, and other properties should be ignored.
注意：
应用程序应确保定期调用consume ()，即使没有预期的消息，为等待调用的排队回调提供服务，当rebalnce_cb已经注册时，这一点尤其重要，因为需要正确地调用和处理它，以同步内部使用者状态。


while (true) {
    $message = $kafkaConsumer->consume(3600e3);
    switch ($message->err) {
        case RD_KAFKA_RESP_ERR_NO_ERROR:
            handle($message);
            break;
        case RD_KAFKA_RESP_ERR__TIMED_OUT:
            echo "Timedout\n";
            break;
        default:
            throw new \Exception($message->errstr());
            break;
    }
}

6)public array RdKafka\KafkaConsumer::getAssignment ( void )
返回由assign设置 或 再平衡的 当前分区分配集
Returns the current partition assignment as set by RdKafka\KafkaConsumer::assign() or by rebalancing.
返回值
Returns an array of RdKafka\TopicPartition 返回RdKafka\Topic分区的数组
Errors/Exceptions
Throws RdKafka\Exception on errors.

6)public RdKafka\Metadata RdKafka\KafkaConsumer::getMetadata ( bool $all_topics , RdKafka\KafkaConsumerTopic $only_topic = NULL , int $timeout_ms)
向代理请求元数据

参数
all_topics (bool)
When TRUE, request info about all topics in cluster. Else, only request info about locally known topics.如果为真，请求有关集群中所有主题的信息。否则，只请求有关本地已知主题的信息
only_topic (RdKafka\KafkaConsumerTopic) 
When non-null, only request info about this topic当非空时，只请求有关此主题的信息。
timeout_ms (int)
Timeout (milliseconds) 超时

返回值
Returns a RdKafka\Metadata instance 
示例
$all = $kafkaConsumer->metadata(true, NULL, 60e3);

$local = $kafkaConsumer->metadata(false, NULL, 60e3);

$topic = $kafkaConsumer->newTopic("myTopic");
$one = $kafkaConsumer->metadata(true, $topic, 60e3);

7)public array RdKafka\KafkaConsumer::getSubscription ( void )
返回RdKafka\KafkaConsumer：subscribe()设置的当前订阅
Return the current subscription as set by RdKafka\KafkaConsumer::subscribe()
返回值
Returns an array of topic names 返回主题名称数组

8)public void RdKafka\KafkaConsumer::subscribe ( array $topics ) 
将订阅集更新为主题。
这将覆盖当前任务。任何先前的订阅都将首先被取消分配和取消订阅。
订阅集表示要消费的所需主题.......
可以通过调用RdKafka\Conf::setDefaultTopicConf()更改订阅主题的默认配置。

$kafkaConsumer->assign([
    "logs",
    "^myPfx[0-9]_.*",
]);

9)public ReturnType RdKafka\KafkaConsumer::unsubscribe ( void )
从当前订阅集取消订阅

RdKafka\KafkaConsumerTopic类
(PECL rdkafka >= 1.0.0, librdkafka >= 0.9)
This class represents a topic when using the RdKafka\KafkaConsumer. It can not be instantiated directly, RdKafka\KafkaConsumer::newTopic() should be used instead.
当想使用RdKafka\KafkaConsumer去表示一个主题的时候，不能直接实例化，应该使用RdKafka\KafkaConsumer::newTopic()替代

1)public void RdKafka\KafkaConsumerTopic::offsetStore ( integer $partition , integer $offset )
Store offset offset for topic partition partition. The offset will be commited (written) to the offset store according to auto.commit.interval.ms.
auto.commit.interval.ms消费者offset提交到zookeeper的频率（以毫秒为单位）（0.9之后就默认存储再broke中了）
auto.commit.enable must be set to false when using this API.使用此API时 auto.commit.enable必须设置为false，如果enable.auto.commit设置为true，则消费者偏移量自动提交给Kafka的频率（以毫秒为单位）。
auto.offset.reset	largest	如果ZooKeeper中没有初始偏移量，或偏移值超出范围，
该怎么办？
最小：自动将偏移重置为最小偏移
最大：自动将偏移重置为最大偏移
* 其他任何事情：抛出异常消费者

参数
partition (integer)
Partition ID
offset (integer)
Offset


2)/* Inherited methods */
public string RdKafka\Topic::getName ( void )

RdKafka类
(PECL rdkafka >= 0.9.1)
This is the base class for low-level clients: RdKafka\Consumer, RdKafka\Producer. This class can not be instanciated directly, use one of the sub classes instead.
这是低级消费者客户端的基类：RdKafka\Consumer，RdKafka\Producer。不能直接实例化这个类，而是使用其中一个子类。

1)public integer RdKafka::addBrokers ( string $broker_list )
将一个或多个代理添加到Kafka句柄的初始引导代理列表中。
当rdkafka通过查询代理元数据连接到代理时，将自动发现其他代理。
如果代理名称解析为多个地址(可能是地址家族)，则所有代理名称都将以循环方式用于连接尝试。
返回值
Returns the number of brokers successfully added.成功添加的代理个数