PHP SplPriorityQueue extractFlags 怎样同时读取优先级和值

如果任务已经放进 SplPriorityQueue，但业务日志还需要同时记录“取出的任务内容”和“它的优先级”，关键设置不是寻找一个叫 extractFlags() 的方法，而是调用 setExtractFlags(SplPriorityQueue::EXTR_BOTH)。这样 top()、current() 和 extract() 都会按同一模式返回包含 data、priority 的数组。

官方手册：https://www.php.net/manual/en/splpriorityqueue.setextractflags.php

本文把它放进一个很小的“任务调度队列”里说明。默认模式是 EXTR_DATA，只返回值；设置为 EXTR_BOTH 后才能一次取得值和优先级。需要注意的是，SplPriorityQueue 是最大堆，优先级相同的元素顺序没有定义。

先确定队列到底返回什么

SplPriorityQueue::insert($value, $priority) 的第一个参数是业务数据，第二个参数是排序依据。队列默认使用 EXTR_DATA，所以直接调用 extract() 只能得到任务内容，优先级已经不在返回值里。

insert('生成日报', 20);
$queue->insert('发送告警', 80);

// 默认是 EXTR_DATA，因此这里只会拿到字符串值。
$task = $queue->extract();
var_dump($task); // string(12) "发送告警"
?>

如果你把返回值强行当成包含优先级的数组，会得到错误的业务判断。先把“值”和“优先级”都作为输出需要，后面的读取方式才不会反复改动。

用 EXTR_BOTH 一次拿到 data 和 priority

设置提取标志后，返回数组会有两个稳定语义：data 是插入时的值，priority 是插入时的优先级。EXTR_PRIORITY 只返回优先级，EXTR_DATA 只返回数据，EXTR_BOTH 才是题目所需的组合模式。

insert(['name' => '生成日报', 'retry' => 0], 20);
$queue->insert(['name' => '发送告警', 'retry' => 1], 80);
$queue->setExtractFlags(SplPriorityQueue::EXTR_BOTH);

// 只查看堆顶，不删除元素；返回数组包含 data 和 priority。
$top = $queue->top();
printf("任务=%s，优先级=%d\n", $top['data']['name'], $top['priority']);

// 取出堆顶后才会从队列中移除它。
$item = $queue->extract();
var_dump($item['data'], $item['priority']);
?>

在这个例子里，top() 可以用来做预览或日志判断，extract() 才代表任务真正离开队列。不要用一次 extract() 来“看看是什么”，否则后续消费者会少拿一个任务。

top、current、extract 的边界要分开

三个方法共享当前提取模式，但职责不同：

如果要把整个队列按优先级读出，可以使用迭代器。current() 返回当前节点，next() 移动到下一个节点；这条路径不等同于对每个节点调用 extract()。

setExtractFlags(SplPriorityQueue::EXTR_BOTH);

foreach ($view as $item) {
    // data 是业务对象，priority 是调度依据。
    echo $item['data']['name'], ':', $item['priority'], PHP_EOL;
}

// 原队列仍然保留，真正执行任务时再 extract()。
if (!$queue->isEmpty()) {
    $next = $queue->extract();
}
?>

复制队列是为了把“观察顺序”和“消费任务”分开。若任务对象本身不可安全复制，应该把需要展示的字段在入队时另存，不能把遍历当作通用的无副作用快照机制。

把读取模式封装成任务调度小工具

实际项目中，建议在创建队列时就固定返回契约，并在处理循环中显式判断空队列。这样调用方不需要猜返回值到底是字符串、优先级还是数组。

queue = new SplPriorityQueue();
        // 统一返回数组，避免不同调用点使用不同提取模式。
        $this->queue->setExtractFlags(SplPriorityQueue::EXTR_BOTH);
    }

    public function push(string $name, int $priority): void
    {
        // 把任务名放进 data，把调度权重单独作为 priority。
        $this->queue->insert(['name' => $name], $priority);
    }

    public function pop(): ?array
    {
        // 空队列不能 extract，先返回 null 让调用方决定如何等待。
        return $this->queue->isEmpty() ? null : $this->queue->extract();
    }

    public function peek(): ?array
    {
        // top 只预览，不改变待处理任务数量。
        return $this->queue->isEmpty() ? null : $this->queue->top();
    }
}

$tasks = new TaskQueue();
$tasks->push('刷新缓存', 30);
$tasks->push('处理支付回调', 100);
$next = $tasks->pop();

if ($next !== null) {
    printf("执行 %s，优先级 %d\n", $next['data']['name'], $next['priority']);
}
?>

这里的 pop() 和 peek() 都返回同一结构，调用方只处理 data 和 priority 两个字段。队列为空时返回 null 是业务层约定，不是 SplPriorityQueue 自动提供的返回值。

三个容易踩到的边界

• 方法名不要混淆。官方接口是 setExtractFlags() 与 getExtractFlags()；“extractFlags”只是对提取标志的泛称，不是可直接调用的方法。
• 相同优先级不要依赖插入顺序。SplPriorityQueue 的相同优先级元素顺序未定义。如果业务要求先进先出，需要把序号并入可比较的 priority，或在 data 中维护二级排序信息并自行处理。
• extract 会消耗元素。日志、预览和调试优先使用 top() 或队列副本；真正执行任务时才调用 extract()。
• 先固定返回模式再写类型判断。默认 EXTR_DATA 返回业务值，切换到 EXTR_BOTH 后返回数组，混用两种模式会让调用方的类型判断失效。

最后用一张表记住选择

因此，PHP 中“同时读取优先级和值”的最小答案就是：创建 SplPriorityQueue 后调用 setExtractFlags(SplPriorityQueue::EXTR_BOTH)，再根据是否要消费元素选择 top() 或 extract()。先把返回契约固定下来，调度代码就不会因为默认的 EXTR_DATA 而丢失优先级。

相关问题

EXTR_BOTH 返回的键名是什么？

返回数组使用 data 和 priority 两个键，分别表示插入时的数据与优先级。

top() 会不会删除最高优先级元素？

不会。top() 只查看堆顶；需要把节点从队列中移除时才调用 extract()。

为什么相同 priority 的任务顺序会变化？

官方类说明没有为相同优先级提供稳定顺序保证。不要把插入先后当作隐含的二级排序规则。