PerfectQueue 技术文档

本文档旨在帮助用户详细了解和正确使用 PerfectQueue 项目，内容包括安装指南、项目使用说明、项目API使用文档以及项目安装方式。

1. 安装指南

PerfectQueue 是基于关系型数据库（RDBMS）构建的高可用分布式队列。以下是安装 PerfectQueue 的步骤：

1. 准备关系型数据库。PerfectQueue 支持的数据库配置在 config/perfectqueue.yml 文件中进行设置。

2. 初始化数据库。使用以下命令初始化 PerfectQueue 后端数据库：

   $ perfectqueue init
   

3. 根据需要配置 config/perfectqueue.yml 文件，包括数据库连接信息、日志文件路径、子进程数量等。

2. 项目使用说明

PerfectQueue 提供了与 Amazon SQS 类似的 API，以下是如何使用 PerfectQueue 的基本步骤：

提交任务

在 Ruby 代码中，使用以下方式提交任务：

PerfectQueue.open(config) do |queue|
  data = {'key' => 'value'}
  queue.submit("task-id", "type1", data)
end

处理任务

要处理任务，你需要创建一个继承自 PerfectQueue::Application::Base 的处理器类，并实现 run 方法：

class TestHandler < PerfectQueue::Application::Base
  def run
    puts "acquired task: #{task.inspect}"
    task.finish!
  end
end

然后，定义一个路由类 PerfectQueue::Application::Dispatch，指定任务类型与处理器的对应关系：

class Dispatch < PerfectQueue::Application::Dispatch
  route "type1" => TestHandler
end

最后，运行工作进程来处理队列中的任务：

$ perfectqueue run -I. -rapp/workers/dispatch Dispatch

3. 项目API使用文档

以下是 PerfectQueue 的主要 API 方法：

• PerfectQueue.open(config, &block): 打开队列。
• Queue#submit(task_id, type, data, options={}): 提交一个新任务。
• Queue#poll: 轮询一个任务（通常不需要直接使用此方法）。
• AcquiredTask#data: 获取与任务关联的数据。
• AcquiredTask#finish!: 完成任务。
• AcquiredTask#retry!: 重试任务。
• Queue#[](key): 创建一个任务引用。
• Task#exists?: 检查任务是否存在。
• Task#force_finish!: 强制完成一个任务。

4. 项目安装方式

PerfectQueue 的安装方式通常有两种：

1. 通过命令行工具 perfectqueue 运行相关的命令，如初始化数据库、提交任务、列出任务、强制完成任务等。
2. 在 Ruby 应用程序中引入 PerfectQueue 库，并按照 API 文档编写代码来使用队列。

确保在运行命令行工具或 Ruby 应用程序之前，已经正确配置了 config/perfectqueue.yml 文件。