<commit_before># Beanstalkd中文协议

### 总括

`beanstalkd` 协议基于 ASCII 编码运行在 tcp 上. 客户端连接服务器并发送指令和数据，然后等待响应并关闭连接. 对于每个连接，服务器按照接收命令的序列依次处理并响应. 所有整型值都非负的十进制数，除非有特别声明.

### 名称约定

所有名称必须是 ASCII 码字符串，即包括：

* **字母** (A-Z and a-z)
* **数字** (0-9)
* **连字符** ("-")
* **加号** ("+")
* **斜线** ("/")
* **分号** (";")
* **点** (".")
* **美元符** ("$")
* **下划线** ("_")
* **括号** ("*(*" and "*)*")

**注意**：名称不能以连字符开始，并且是以空白字符结束，每个名称至少包含一个字符.

### 错误说明

| 返回的错误                               | 描述       |
| --------------------------------------- | -------- |
| `OUT_OF_MEMORY\r\n`                     | 服务器没有足够的内存分配给特定的 job，客户端应该稍后重试 |
| `INTERNAL_ERROR\r\n`                    | 服务器内部错误，该错误不应该发生，如果发生了，请报告: [http://groups.google.com/group/beanstalk-talk](http://groups.google.com/group/beanstalk-talk).|
| `BAD_FORMAT\r\n`                         | 格式不正确，客户端发送的指令格式出错，有可能不是以 `\r\n` 结尾，或者要求整型值等等 |
| `UNKNOWN_COMMAND\r\n`                   | 未知的命令，客户端发送的指令服务器不理解 |

### job 的生命周期

Client 使用 put 命令创建一个工作任务 job. 在整个生命周期中 job 可能有四个工作状态：ready、reserved、delayed、buried. 在 put 操作之后，一个 job 的典型状态是 ready，在 ready 队列中，它将等待一个 worker 取出此 job 并设置为其为 reserved 状态. worker占有此 job 并执行，当 job 执行完毕，worker 可以发送一个 delete 指令删除此 job.

| Status              | Description   |
| --------------------| ------------- |
| `ready`             | 等待被取出并处理 |
| `reserved`          | 如果 job 被 worker 取出，将被此 worker 预订，worker 将执行此 job |
| `delayed`           | 等待特定时间之后，状态再迁移为 `ready` 状态 |
| `buried`            | 等待唤醒，通常在 job 处理失败时进入该状态

#### job 典型的生命周期

```text
   put            reserve               delete
  -----> [READY] ---------> [RESERVED] --------> *poof*
```

#### job 可能的状态迁移

```text
   put with delay               release with delay
  ----------------> [DELAYED] <------------.
                        |                   |
                 kick   | (time passes)     |
                        |                   |
   put                  v     reserve       |       delete
  -----------------> [READY] ---------> [RESERVED] --------> *poof*
                       ^  ^                |  |
                       |   \  release      |  |
                       |    `-------------'   |
                       |                      |
                       | kick                 |
                       |                      |
                       |       bury           |
                    [BURIED] <---------------'
                       |
                       |  delete
                        `--------> *poof*
```

## Tubes

一个 beanstalkd 实例服务可能有一个或者多个 tube，用来储存统一类型的 job.每个 tube 由一个就绪 (`ready`) 队列与延迟 (`delayed`) 队列组成.每个 job 所有的状态迁移在一个 tube 中完成.通过发送 `watch` 指令, 消费者 consumers 可以监控感兴趣的 tube.通过发送 `ignore` 指令, 消费者 consumers 可以取消监控 tube.通过 `list-tubes-watched`命令返回所有监控的 tubes，当客户端预订 (`reserved`) 一个 job，此 job 可能来自任何一个它监控的 tube.

当一个客户端连接上服务器时，客户端监控的 tube 默认为 `defaut`，如果客户端提交 job 时，没有使用 `use` 命令，那么这些 job 就存于名为`default`的 tube 中.

tube 按需求创建，无论他们在什么时候被引用到.如果一个 tube 变为空（即 no ready jobs，no delayed jobs，no buried jobs）和没有任何客户端引用(being watched)，它将会被**自动删除**.

### 指令说明（Commands）

#### 生产者指令说明（Producer Commands）

#### `put`

插入一个 job 到队列

**指令格式**

```text
put <pri> <delay> <ttr> <bytes>\r\n
<data>\r\n
```

* `<pri>` 整型值, 为优先级, 可以为0-2^32 (4,294,967,295) 值越小优先级越高, 默认为1024.
* `<delay>` 整型值，延迟`ready`的秒数，在这段时间 job 为 `delayed` 状态.
* `<ttr>` -- time to run --整型值，允许 worker 执行的最大秒数，如果 worker 在这段时间不能 delete，release，bury job，那么当 job 超时，服务器将**自动** release 此job，此 job 的状态迁移为`ready`. 最小为 1 秒，如果客户端指定为 0 将会被重置为 1.
* `<bytes>` 整型值，job body的长度，不包含`\r\n`，这个值必须小于 `max-job-size`，默认为 2^16.
* `<data>`   job body

**响应**

```text
INSERTED <id>\r\n
```

表示插入 job 成功，id 为新 job 的任务标识，整型值 (uint64)

```text
BURIED <id>\r\n
```

如服务器为了增加队列的优先级而，内存不足时返回，id 为新 job 的任务标识，整型值 (uint64)
<commit_msg>add delay ttr maximum value to chinese doc<commit_after># Beanstalkd中文协议

### 总括

`beanstalkd` 协议基于 ASCII 编码运行在 tcp 上. 客户端连接服务器并发送指令和数据，然后等待响应并关闭连接. 对于每个连接，服务器按照接收命令的序列依次处理并响应. 所有整型值都非负的十进制数，除非有特别声明.

### 名称约定

所有名称必须是 ASCII 码字符串，即包括：

* **字母** (A-Z and a-z)
* **数字** (0-9)
* **连字符** ("-")
* **加号** ("+")
* **斜线** ("/")
* **分号** (";")
* **点** (".")
* **美元符** ("$")
* **下划线** ("_")
* **括号** ("*(*" and "*)*")

**注意**：名称不能以连字符开始，并且是以空白字符结束，每个名称至少包含一个字符.

### 错误说明

| 返回的错误                               | 描述       |
| --------------------------------------- | -------- |
| `OUT_OF_MEMORY\r\n`                     | 服务器没有足够的内存分配给特定的 job，客户端应该稍后重试 |
| `INTERNAL_ERROR\r\n`                    | 服务器内部错误，该错误不应该发生，如果发生了，请报告: [http://groups.google.com/group/beanstalk-talk](http://groups.google.com/group/beanstalk-talk).|
| `BAD_FORMAT\r\n`                         | 格式不正确，客户端发送的指令格式出错，有可能不是以 `\r\n` 结尾，或者要求整型值等等 |
| `UNKNOWN_COMMAND\r\n`                   | 未知的命令，客户端发送的指令服务器不理解 |

### job 的生命周期

Client 使用 put 命令创建一个工作任务 job. 在整个生命周期中 job 可能有四个工作状态：ready、reserved、delayed、buried. 在 put 操作之后，一个 job 的典型状态是 ready，在 ready 队列中，它将等待一个 worker 取出此 job 并设置为其为 reserved 状态. worker占有此 job 并执行，当 job 执行完毕，worker 可以发送一个 delete 指令删除此 job.

| Status              | Description   |
| --------------------| ------------- |
| `ready`             | 等待被取出并处理 |
| `reserved`          | 如果 job 被 worker 取出，将被此 worker 预订，worker 将执行此 job |
| `delayed`           | 等待特定时间之后，状态再迁移为 `ready` 状态 |
| `buried`            | 等待唤醒，通常在 job 处理失败时进入该状态

#### job 典型的生命周期

```text
   put            reserve               delete
  -----> [READY] ---------> [RESERVED] --------> *poof*
```

#### job 可能的状态迁移

```text
   put with delay               release with delay
  ----------------> [DELAYED] <------------.
                        |                   |
                 kick   | (time passes)     |
                        |                   |
   put                  v     reserve       |       delete
  -----------------> [READY] ---------> [RESERVED] --------> *poof*
                       ^  ^                |  |
                       |   \  release      |  |
                       |    `-------------'   |
                       |                      |
                       | kick                 |
                       |                      |
                       |       bury           |
                    [BURIED] <---------------'
                       |
                       |  delete
                        `--------> *poof*
```

## Tubes

一个 beanstalkd 实例服务可能有一个或者多个 tube，用来储存统一类型的 job.每个 tube 由一个就绪 (`ready`) 队列与延迟 (`delayed`) 队列组成.每个 job 所有的状态迁移在一个 tube 中完成.通过发送 `watch` 指令, 消费者 consumers 可以监控感兴趣的 tube.通过发送 `ignore` 指令, 消费者 consumers 可以取消监控 tube.通过 `list-tubes-watched`命令返回所有监控的 tubes，当客户端预订 (`reserved`) 一个 job，此 job 可能来自任何一个它监控的 tube.

当一个客户端连接上服务器时，客户端监控的 tube 默认为 `defaut`，如果客户端提交 job 时，没有使用 `use` 命令，那么这些 job 就存于名为`default`的 tube 中.

tube 按需求创建，无论他们在什么时候被引用到.如果一个 tube 变为空（即 no ready jobs，no delayed jobs，no buried jobs）和没有任何客户端引用(being watched)，它将会被**自动删除**.

### 指令说明（Commands）

#### 生产者指令说明（Producer Commands）

#### `put`

插入一个 job 到队列

**指令格式**

```text
put <pri> <delay> <ttr> <bytes>\r\n
<data>\r\n
```

* `<pri>` 整型值, 为优先级, 可以为0-2^32 (4,294,967,295) 值越小优先级越高, 默认为1024.
* `<delay>` 整型值，延迟`ready`的秒数，在这段时间 job 为 `delayed` 状态. 最大 delay 值为 2^32-1.
* `<ttr>` -- time to run --整型值，允许 worker 执行的最大秒数，如果 worker 在这段时间不能 delete，release，bury job，那么当 job 超时，服务器将**自动** release 此job，此 job 的状态迁移为`ready`. 最小为 1 秒，如果客户端指定为 0 将会被重置为 1. 最大 ttr 值为 2^32-1.
* `<bytes>` 整型值，job body的长度，不包含`\r\n`，这个值必须小于 `max-job-size`，默认为 2^16.
* `<data>`   job body

**响应**

```text
INSERTED <id>\r\n
```

表示插入 job 成功，id 为新 job 的任务标识，整型值 (uint64)

```text
BURIED <id>\r\n
```

如服务器为了增加队列的优先级而，内存不足时返回，id 为新 job 的任务标识，整型值 (uint64)

{'fraction_non_alphanumeric': 0.19732131017106486, 'fraction_numerical': 0.009017371701365866, 'mean_word_length': 1.6315422191207258, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 43, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 24, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7447597', 'n_tokens_mistral': 3845, 'n_tokens_neox': 4130, 'n_words': 565}