pcntl_alarm() 結合 pcntl_signal() 實作進程級別的鬧鐘訊號。當指定秒數到達,核心發送 SIGALRM 訊號給進程,觸發註冊的處理函式,在其中拋出異常即可強制中斷長時間運行的函式。
pcntl_alarm(int $seconds): int
--enable-pcntl,僅支援 CLI 模式,不支援 Web 伺服器環境<?php
// 必須宣告 tick 讓 PHP 檢查訊號
declare(ticks = 1);
// 1. 定義訊號處理器:拋出異常中斷執行
function timeoutHandler(int $signo) {
throw new RuntimeException("執行逾時(SIGALRM)");
}
// 2. 註冊 SIGALRM 訊號處理器
pcntl_signal(SIGALRM, "timeoutHandler");
// 3. 目標函式:模擬長時間運行
function longRunningTask() {
sleep(10); // 模擬耗時操作
echo "任務正常完成\n";
}
function quickTask() {
usleep(100000); // 0.1 秒
echo "快速任務完成\n";
}
function otherTask() {
echo "其他後續任務\n";
}
try {
// 設定 1 秒鬧鐘
pcntl_alarm(1);
// 執行長任務(將被中斷)
longRunningTask();
// 正常完成則取消鬧鐘
pcntl_alarm(0);
} catch (RuntimeException $e) {
echo "捕獲逾時:" . $e->getMessage() . "\n";
}
// 程式繼續執行後續邏輯
otherTask();
quickTask();
otherTask();
?>
捕獲逾時:執行逾時(SIGALRM)
其他後續任務
快速任務完成
其他後續任務
<?php
declare(ticks = 1);
class TimeoutExecutor {
private $originalHandler;
public function __construct() {
// 保存原有處理器(如有)
$this->originalHandler = pcntl_signal_get_handler(SIGALRM);
}
/**
* 執行可中斷的呼叫
* @param callable $callable 要執行的函式
* @param int $seconds 逾時秒數
* @param mixed ...$args 傳遞參數
* @return mixed 函式回傳值
* @throws RuntimeException 逾時或訊號錯誤
*/
public function execute(callable $callable, int $seconds, ...$args) {
if ($seconds <= 0) {
return $callable(...$args); // 無逾時限制直接執行
}
// 設定新處理器
pcntl_signal(SIGALRM, [$this, 'signalHandler']);
// 啟動鬧鐘
pcntl_alarm($seconds);
try {
$result = $callable(...$args);
// 正常完成,取消鬧鐘
pcntl_alarm(0);
return $result;
} catch (RuntimeException $e) {
// 確保鬧鐘取消
pcntl_alarm(0);
throw $e;
} finally {
// 還原原有處理器
if ($this->originalHandler !== false && $this->originalHandler !== SIG_DFL) {
pcntl_signal(SIGALRM, $this->originalHandler);
} else {
pcntl_signal(SIGALRM, SIG_DFL);
}
}
}
private function signalHandler(int $signo) {
if ($signo === SIGALRM) {
throw new RuntimeException("函式執行超過 {$seconds} 秒逾時");
}
}
}
// 使用範例
$executor = new TimeoutExecutor();
try {
$result = $executor->execute(function() {
sleep(5);
return "完成";
}, 2); // 2 秒逾時
echo "結果: $result\n";
} catch (RuntimeException $e) {
echo "逾時: " . $e->getMessage() . "\n";
}
echo "主程式繼續運行\n";
?>
# 進入 PHP 原始碼擴展目錄
cd /usr/local/src/php-版本/ext/pcntl
# 生成 configure 腳本
phpize
# 配置(指定 php-config 路徑)
./configure --with-php-config=/usr/local/php/bin/php-config
# 編譯安裝
make && make install
# php.ini 加入擴展
echo "extension=pcntl.so" >> /usr/local/php/etc/php.ini
# 重啟 PHP-FPM
systemctl restart php-fpm
# Ubuntu/Debian
apt-get install php-pcntl
# 或特定版本
apt-get install php8.2-pcntl
# CentOS/RHEL
yum install php-pcntl
# 或
dnf install php-pcntl
# Alpine
apk add php82-pcntl
php -m | grep pcntl
# 或
php -r "echo extension_loaded('pcntl') ? '已載入' : '未載入';"
| 限制 | 說明 | 替代方案 |
|---|---|---|
| 僅 CLI 模式 | Web (FPM/Apache) 進程不支援 pcntl | Web 端用 set_time_limit()、max_execution_time、異步隊列 |
| 非 Windows 原生支援 | Windows PHP 不支援 pcntl | WSL2、Docker Linux 容器、異步處理 |
| 訊號處理器限制 | 處理器內不能做複雜操作,只能設旗標/拋異常 | 保持處理器極簡 |
| declare(ticks=1) 必須 | 否則 PHP 不會檢查訊號,鬧鐘不觸發 | 在檔案頂部宣告 |
| 多執行緒不安全 | pcntl 僅單進程,不支援 pthreads | 用多進程或異步框架 |
| 資源洩漏風險 | 逾時中斷可能留下開啟的連線、鎖、檔案 | 使用 try/finally、註冊關閉函式 |
<?php
// 重設腳本最大執行時間(秒)
set_time_limit(30); // 從現在起再給 30 秒
// 在長時間迴圈中定期重設
foreach ($largeDataset as $item) {
process($item);
if (++$count % 100 === 0) {
set_time_limit(30); // 延長執行時間
}
}
?>
# 使用 Redis + Worker 或專用隊列
# 生產者
$redis->lpush('queue:tasks', json_encode(['type' => 'heavy_job', 'data' => $id]));
# 消費者 - 長時間運行獨立進程
while (true) {
$task = $redis->brpop('queue:tasks', 5);
if ($task) {
processHeavyJob(json_decode($task[1], true));
}
}
<?php
// Swoole 協程超時控制
Co\run(function() {
$channel = new Chan();
// 子協程執行耗時任務
go(function() use ($channel) {
$result = heavyComputation();
$channel->push($result);
});
// 主協程等待 2 秒
if ($channel->pop(2.0) === false) {
echo "任務逾時\n";
// 可選:殺掉子協程或標記取消
} else {
echo "結果: $result\n";
}
});
?>
pcntl_alarm() 提供進程級硬性逾時中斷能力,適合 CLI 長時間任務、守護進程、批次處理、測試框架。核心模式:declare(ticks=1) + pcntl_signal(SIGALRM, handler) + pcntl_alarm(秒數) + try/catch。Web 環境不可用,請改用 set_time_limit()、異步隊列或 Swoole 協程超時控制。