@spec child_spec(pool_opts_t()) :: Supervisor.child_spec()

返回用于监督树的子进程规范。

此函数用于生成连接池的监督树子进程规范，便于将连接池添加到应用程序的监督树中。

参数

• opts: 连接池配置选项，必须包含 :name 字段

返回值

返回一个符合监督树子进程规范的映射，包含 :id 和 :start 字段

示例

iex> opts = [name: MyRedis.Pool, url: "redis://:password@localhost:6379", pool_size: 5]
iex> RedisPool.Core.child_spec(opts)
%{id: {RedisPool.Core, MyRedis.Pool}, start: {RedisPool.Core, :start_link, [[name: MyRedis.Pool, url: "redis://:password@localhost:6379", pool_size: 5]]}}

@spec command(pid() | atom(), command_t(), command_opts_t()) ::
  {:ok, redis_response_t()} | {:error, RedisPool.Error.t()}

执行 Redis 命令。

此函数从连接池中获取一个连接，执行指定的 Redis 命令，然后将连接归还给连接池。 它是 Redix.command/3 函数的包装，提供了连接池管理和错误处理功能。

参数

• name: 连接池的名称或 PID
• command: Redis 命令，表示为字符串列表，例如 ["SET", "key", "value"]
• opts: 命令选项，包括：
  • :pool_timeout - 获取连接的超时时间（毫秒），默认为 5000
  • :retry_count - 命令执行失败时的重试次数，默认为 0
  • 其他选项将传递给 Redix.command/3

返回值

• {:ok, result} - 命令执行成功，返回命令结果
• {:error, error} - 命令执行失败，返回错误信息

示例

iex> RedisPool.Core.command(pool, ["SET", "foo", "bar"])
{:ok, "OK"}

iex> RedisPool.Core.command(pool, ["GET", "foo"])
{:ok, "bar"}

iex> RedisPool.Core.command(pool, ["INCR", "counter"])
{:ok, 1}

iex> RedisPool.Core.command(pool, ["KEYS", "f*"])
{:ok, ["foo"]}

错误处理

可能返回的错误包括：

• 连接池超时 - 无法在指定时间内获取连接
• 连接错误 - 执行命令时连接断开
• 命令错误 - Redis 服务器返回错误
• 超时错误 - 命令执行超时

@spec handle_checkin(connection_state_t(), term(), connection_state_t(), String.t()) ::
  {:ok, connection_state_t(), String.t()}

NimblePool 回调函数：处理连接归还。

此函数在连接归还到连接池时被 NimblePool 调用。 它接受归还的连接，并更新连接池状态。

参数

• conn: 要归还的连接状态
• _checkin_reason: 归还原因（未使用）
• _old_conn: 检出时的连接状态（未使用）
• pool_state: 连接池状态

返回值

• {:ok, conn, pool_state} - 连接归还成功

@spec handle_checkout(:checkout, GenServer.from(), connection_state_t(), String.t()) ::
  {:ok, connection_state_t(), connection_state_t(), String.t()}

NimblePool 回调函数：处理连接检出。

此函数在从连接池检出连接时被 NimblePool 调用。 它返回连接状态，以便客户端可以使用连接。

参数

• checkout_reason: 检出原因，当前仅支持 :checkout
• from: 请求连接的客户端进程信息
• conn: 当前连接状态
• pool_state: 连接池状态

返回值

• {:ok, checkout_result, conn, pool_state} - 连接检出成功

@spec handle_info(:close | term(), connection_state_t()) ::
  {:remove, :closed} | {:ok, connection_state_t()}

NimblePool 回调函数：处理进程消息。

此函数在连接池工作进程收到消息时被 NimblePool 调用。 它处理特定的消息，如连接关闭请求。

参数

• message: 收到的消息
• conn: 当前连接状态

返回值

• {:remove, :closed} - 连接应该被移除
• {:ok, conn} - 连接应该保持活跃

@spec handle_ping(connection_state_t(), String.t()) ::
  {:ok, connection_state_t()} | {:remove, :closed}

NimblePool 回调函数：处理连接健康检查。

此函数定期被 NimblePool 调用，用于检查连接的健康状态。 它向 Redis 服务器发送 PING 命令，并根据响应决定连接是否健康。

参数

• conn: 当前连接状态
• _pool_state: 连接池状态

返回值

• {:ok, conn} - 连接健康，可以继续使用
• {:remove, reason} - 连接不健康，应该被移除，原因包括：
  • :invalid_response - 收到非预期的响应
  • :connection_error - 连接错误
  • :timeout - 健康检查超时
  • :command_error - 命令执行错误
  • :exception - 发生异常
  • :connection_closed - 连接已关闭

@spec init_worker(String.t()) ::
  {:ok, connection_state_t(), String.t()} | {:error, RedisPool.Error.t()}

NimblePool 回调函数：初始化工作进程。

此函数在创建新的连接池工作进程时被 NimblePool 调用。 它负责创建到 Redis 服务器的新连接，并返回连接状态。

参数

• redis_url: Redis 服务器的 URL

返回值

• {:ok, conn, pool_state} - 连接成功创建
• {:error, error} - 连接创建失败

@spec pipeline(pid() | atom(), [command_t()], command_opts_t()) ::
  {:ok, [redis_response_t()]} | {:error, RedisPool.Error.t()}

执行 Redis 管道命令。

此函数从连接池中获取一个连接，执行一系列 Redis 命令作为管道操作，然后将连接归还给连接池。 管道操作可以显著提高多个命令执行的性能，因为它们在一个网络往返中发送和接收。 它是 Redix.pipeline/3 函数的包装，提供了连接池管理和错误处理功能。

参数

• name: 连接池的名称或 PID
• commands: Redis 命令列表，每个命令表示为字符串列表，例如 [["SET", "key1", "value1"], ["SET", "key2", "value2"]]
• opts: 命令选项，包括：
  • :pool_timeout - 获取连接的超时时间（毫秒），默认为 5000
  • :retry_count - 命令执行失败时的重试次数，默认为 0
  • 其他选项将传递给 Redix.pipeline/3

返回值

• {:ok, results} - 管道命令执行成功，返回每个命令的结果列表
• {:error, error} - 管道命令执行失败，返回错误信息

示例

iex> RedisPool.Core.pipeline(pool, [["SET", "foo", "bar"], ["SET", "bar", "foo"]])
{:ok, ["OK", "OK"]}

iex> RedisPool.Core.pipeline(pool, [["GET", "foo"], ["GET", "bar"]])
{:ok, ["bar", "foo"]}

iex> RedisPool.Core.pipeline(pool, [["INCR", "counter"], ["INCR", "counter"]])
{:ok, [1, 2]}

错误处理

可能返回的错误包括：

• 连接池超时 - 无法在指定时间内获取连接
• 连接错误 - 执行命令时连接断开
• 命令错误 - Redis 服务器返回错误
• 超时错误 - 命令执行超时

@spec start_link(pool_opts_t()) :: GenServer.on_start()

启动一个 Redis 连接池。

此函数创建并启动一个新的 Redis 连接池，使用 NimblePool 作为底层实现。 连接池创建后，将按照配置的大小预先创建若干连接，并在需要时自动管理这些连接。

参数

• opts: 连接池配置选项，包括：
  • :name - 连接池名称 (必需)
  • :url - Redis 服务器 URL (必需)，格式为 "redis://:password@host:port/db"
  • :pool_size - 连接池大小，默认为 10

返回值

• {:ok, pid} - 连接池成功启动，返回连接池进程 PID
• {:error, reason} - 连接池启动失败，返回失败原因

示例

iex> opts = [url: "redis://:123456@localhost:6379", pool_size: 10, name: :my_pool]
iex> {:ok, pid} = RedisPool.Core.start_link(opts)
iex> is_pid(pid)
true

错误处理

如果提供的选项无效或者无法连接到 Redis 服务器，将返回 {:error, reason} 元组。 常见的错误原因包括：

• 无效的 URL 格式
• 无法连接到指定的主机或端口
• 认证失败
• 连接超时

@spec stop(pid() | atom()) :: :ok

停止指定的 Redis 连接池。

此函数用于正常关闭连接池，它会优雅地关闭所有连接并释放相关资源。

参数

• name: 连接池的名称或 PID

返回值

• :ok - 连接池成功停止

示例

iex> {:ok, _pid} = RedisPool.Core.start_link([url: "redis://localhost:6379", pool_size: 5, name: :test_pool])
iex> RedisPool.Core.stop(:test_pool)
:ok

@spec terminate_worker(term(), connection_state_t(), String.t()) :: {:ok, String.t()}

NimblePool 回调函数：终止工作进程。

此函数在连接池工作进程终止时被 NimblePool 调用。 它负责优雅地关闭 Redis 连接并清理资源。

参数

• _reason: 终止原因
• conn: 当前连接状态
• pool_state: 连接池状态

返回值

• {:ok, pool_state} - 连接成功终止