実行タスクを作成する (sys.task)

宣言

タスク = sys.task(実行ファイルのパス [, パラメータ...])

引数

• 実行ファイルのパス
  文字列
• パラメータ...
  文字列。省略可能な可変長引数。デフォルトなし

戻り値

• タスク
  実行タスクオブジェクト。タスクの制御または実行に使用するオブジェクトを返します

タスクオブジェクトのメソッド一覧

メソッド	引数	戻り値	説明
:launch()			タスクを起動し、非同期で実行します
:wait_until_exit()			タスクの終了を同期的に待機します。タスクが終了するまで全スレッドをブロックします。
:set_stdin(入力ストリーム)	パイプ | 文字列		タスクの入力ストリームを設定します。引数には "std"、"/dev/null"、ファイルパス、パイプオブジェクトを指定できます。タスク起動後に呼び出すとエラーが発生します
:stdin()		パイプ | 文字列	タスクの入力ストリームを取得します。"std"、"/dev/null"、ファイルパス、パイプオブジェクトのいずれかが返る場合があります
:set_stdout(出力ストリーム)	パイプ | 文字列		タスクの出力ストリームを設定します。引数には "std"、"/dev/null"、ファイルパス、パイプオブジェクトを指定できます。タスク起動後に呼び出すとエラーが発生します
:stdout()		パイプ | 文字列	タスクの出力ストリームを取得します。"std"、"/dev/null"、ファイルパス、パイプオブジェクトのいずれかが返る場合があります
:set_stderr(エラーストリーム)	パイプ | 文字列		タスクのエラーストリームを設定します。引数には "std"、"/dev/null"、ファイルパス、パイプオブジェクトを指定できます。タスク起動後に呼び出すとエラーが発生します
:stderr()		パイプ | 文字列	タスクのエラーストリームを取得します。"std"、"/dev/null"、ファイルパス、パイプオブジェクトのいずれかが返る場合があります
:set_work_dir(ディレクトリ)	文字列		タスクの作業ディレクトリを設定します。タスク起動後に呼び出すとエラーが発生します
:work_dir()		文字列	タスクの作業ディレクトリを取得します
:set_env(環境変数)	テーブル		タスクの環境変数をキーと値の辞書として設定します。タスク起動後に呼び出すとエラーが発生します
:env()		テーブル	タスクの環境変数をキーと値の辞書として取得します
:pid()		整数	タスクのプロセス ID を取得します。タスク起動前に取得した場合は 0 を返します
:is_running()		ブール値	タスクが実行中かどうかを判定します。:is_running() が false を返した場合でも、ゾンビプロセスの発生を防ぐため、タスクに対して :wait_until_exit() を一度呼び出す必要があります
:interrupt()		ブール値	タスクのメインプロセスに終了用の SIGINT シグナルを送信します
:terminate()		ブール値	タスクのメインプロセスに終了用の SIGTERM シグナルを送信します
:kill()		ブール値	タスクの全プロセスに強制終了用の SIGKILL シグナルを送信します。タスクオブジェクトが回収されると kill 操作が自動的に実行されます
:termination_status()		整数	タスクの終了ステータスを取得します。タスクがまだ終了していない場合は nil とエラー情報を返します
:termination_reason()		文字列	タスクの終了理由を取得します。タスクがまだ終了していない場合は nil とエラー情報を返します

パイプオブジェクトのメソッド一覧

メソッド	引数	戻り値	説明
:read()		文字列	パイプから準備済みのデータを読み取ります
:write(データ)	文字列		パイプにデータを書き込みます
:wclose()		ブール値, nil | 文字列	パイプの書き込み側を閉じます。成功時は true、失敗時は false, エラー情報 を返します
:rclose()		ブール値, nil | 文字列	パイプの読み取り側を閉じます。成功時は true、失敗時は false, エラー情報 を返します

説明

実行タスクを作成し、実行タスクオブジェクトを返します
タスクの完了を待つ間に全スレッドをブロックしたくない場合は、タスクオブジェクトの :is_running() を繰り返し呼び出して、タスクが実行中かどうかを確認できます。終了後に :wait_until_exit() を一度呼び出し、タスクが終了したことを確認してください
この関数は 20250705 以降のバージョンでのみ使用できます

例

-- 次の Shell コマンドを再現
-- echo "你好世界" | /usr/bin/gzip -fc | /usr/bin/gzip -dfc

local comp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-fc')    -- 圧縮タスクを作成
local decomp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-dfc') -- 展開タスクを作成

decomp_tsk:set_stdin(comp_tsk:stdout()) -- 展開タスクの入力ストリームに圧縮タスクの出力ストリームを設定

decomp_tsk:launch() -- 展開タスクを起動
comp_tsk:launch() -- 圧縮タスクを起動

comp_tsk:stdin():write("你好世界") -- 圧縮タスクの入力ストリームにデータを書き込む
comp_tsk:stdin():wclose() -- 圧縮タスクの入力ストリームの書き込み側を閉じ、入力の完了を示す

comp_tsk:wait_until_exit() -- 圧縮タスクの終了を待機
decomp_tsk:wait_until_exit() -- 展開タスクの終了を待機

nLog(decomp_tsk:stdout():read()) -- 展開タスクの出力ストリームを読み取り、"你好世界" を出力

例（TrollStore Persistence Helper の更新を呼び出す）

local persistence_helper_path = app.bundle_path('com.apple.tips')
if not persistence_helper_path then
    nLog('没有检测到 Tips.app，请先从 AppStore 安装 Tips（提示）应用')
    return
end
local root_helper_path = persistence_helper_path..'/trollstorehelper'
if file.exists(root_helper_path) ~= 'file' then
    nLog('未注入巨魔持久助手到 Tips，请先从 TrollStore -> Settings -> Install Persistence Helper 选择 Tips 注入')
    return
end
local tsk = sys.task(root_helper_path, 'refresh')
tsk:launch()
tsk:wait_until_exit()
sys.killall(9, 'SpringBoard', 'backboardd')

例（TrollStore で App のインストールとアンインストールを行い、アイコンキャッシュを再構築する）

local function _trollstorehelper(...)
    local troll_path = app.bundle_path('com.opa334.TrollStore')
    assert(type(troll_path) == 'string', 'TrollStore needs to be installed.')
    local tsk = sys.task(troll_path..'/trollstorehelper', ...)
    tsk:set_stdin('/dev/null')
    tsk:launch()
    local outbuf = {}
    local errbuf = {}
    local function drain_stream(stream, buf)
        local data = stream:read('nb')
        if data and #data > 0 then
            buf[#buf + 1] = data
        end
    end
    while tsk:is_running() do
        drain_stream(tsk:stdout(), outbuf)
        drain_stream(tsk:stderr(), errbuf)
        sys.msleep(100)
    end
    tsk:wait_until_exit()
    drain_stream(tsk:stdout(), outbuf)
    drain_stream(tsk:stderr(), errbuf)
    if tsk:termination_status() == 0 then
        local ret = table.concat(outbuf)
        return ret
    else
        local ret = table.concat(errbuf)
        return nil, ret
    end
end

--- TrollStore を使用して App をインストール
---@param ipapath string インストールパッケージのパス
---@return string? インストール結果のテキスト。失敗時は nil
---@return string? エラー情報。成功時は nil
function troll_install(ipapath)
    return _trollstorehelper('install', ipapath)
end

--- TrollStore でインストールした App をアンインストール
---@param bid string App のバンドル識別子
---@return string? アンインストール結果のテキスト。失敗時は nil
---@return string? エラー情報。成功時は nil
function troll_uninstall(bid)
    return _trollstorehelper('uninstall', bid)
end

--- TrollStore のアイコンキャッシュを再構築。完了まで時間がかかる場合があります
---@return string? 再構築結果のテキスト。失敗時は nil
---@return string? エラー情報。成功時は nil
function troll_rebuild_icon_cache()
    return _trollstorehelper('refresh-all')
end

-- 呼び出し例
nLog(troll_install(XXT_SCRIPTS_PATH..'/TrollDecrypt.tipa')) -- TrollDecrypt をインストール
nLog(troll_uninstall('com.fiore.trolldecrypt')) -- TrollDecrypt をアンインストール
nLog(troll_rebuild_icon_cache()) -- アイコンキャッシュを再構築