Criar uma tarefa executável (sys.task)

Declaração

tarefa = sys.task(caminho_do_executável [, argumentos...])

Parâmetros

• caminho do executável
  Texto.
• argumentos...
  Texto; argumentos opcionais variáveis. O padrão é nenhum.

Valor retornado

• tarefa
  Objeto de tarefa executável; retorna um objeto para controlar ou executar a tarefa.

Lista de métodos do objeto tarefa

Método	Parâmetros	Valor retornado	Descrição
:launch()			Inicia a tarefa de forma assíncrona.
:wait_until_exit()			Aguarda a tarefa terminar de forma síncrona; bloqueia todas as threads até o término.
:set_stdin(fluxo_de_entrada)	pipe | texto		Define o fluxo de entrada da tarefa. O parâmetro pode ser "std", "/dev/null", um caminho de arquivo ou um objeto pipe. Chamá-lo após iniciar a tarefa causará um erro.
:stdin()		pipe | texto	Obtém o fluxo de entrada da tarefa. Pode retornar "std", "/dev/null", um caminho de arquivo ou um objeto pipe.
:set_stdout(fluxo_de_saída)	pipe | texto		Define o fluxo de saída da tarefa. O parâmetro pode ser "std", "/dev/null", um caminho de arquivo ou um objeto pipe. Chamá-lo após iniciar a tarefa causará um erro.
:stdout()		pipe | texto	Obtém o fluxo de saída da tarefa. Pode retornar "std", "/dev/null", um caminho de arquivo ou um objeto pipe.
:set_stderr(fluxo_de_erro)	pipe | texto		Define o fluxo de erro da tarefa. O parâmetro pode ser "std", "/dev/null", um caminho de arquivo ou um objeto pipe. Chamá-lo após iniciar a tarefa causará um erro.
:stderr()		pipe | texto	Obtém o fluxo de erro da tarefa. Pode retornar "std", "/dev/null", um caminho de arquivo ou um objeto pipe.
:set_work_dir(diretório)	texto		Define o diretório de trabalho da tarefa. Chamá-lo após iniciar a tarefa causará um erro.
:work_dir()		texto	Obtém o diretório de trabalho da tarefa.
:set_env(variáveis_de_ambiente)	tabela		Define o dicionário de pares chave-valor das variáveis de ambiente da tarefa. Chamá-lo após iniciar a tarefa causará um erro.
:env()		tabela	Obtém o dicionário de pares chave-valor das variáveis de ambiente da tarefa.
:pid()		inteiro	Obtém o PID da tarefa; antes de iniciá-la, retorna 0.
:is_running()		booleano	Verifica se a tarefa está em execução. Mesmo que :is_running() retorne false, ainda é necessário chamar :wait_until_exit() uma vez para impedir a criação de um processo zumbi.
:interrupt()		booleano	Envia o sinal de interrupção SIGINT ao processo principal da tarefa.
:terminate()		booleano	Envia o sinal de encerramento SIGTERM ao processo principal da tarefa.
:kill()		booleano	Envia o sinal de encerramento forçado SIGKILL a todos os processos da tarefa; a operação kill é executada automaticamente quando o objeto tarefa é coletado.
:termination_status()		inteiro	Obtém o status de encerramento da tarefa; se ela ainda não terminou, retorna nil e uma mensagem de erro.
:termination_reason()		texto	Obtém o motivo do encerramento da tarefa; se ela ainda não terminou, retorna nil e uma mensagem de erro.

Lista de métodos do objeto pipe

Método	Parâmetros	Valor retornado	Descrição
:read()		string	Lê os dados já disponíveis no pipe.
:write(dados)	string		Escreve dados no pipe.
:wclose()		booleano, nil | texto	Fecha a extremidade de escrita do pipe; retorna true em caso de sucesso e false, mensagem de erro em caso de falha.
:rclose()		booleano, nil | texto	Fecha a extremidade de leitura do pipe; retorna true em caso de sucesso e false, mensagem de erro em caso de falha.

Descrição

Cria uma tarefa executável e retorna um objeto de tarefa executável.
Se você não quiser bloquear todas as threads aguardando a conclusão, chame :is_running() do objeto tarefa em um loop para verificar se ela ainda está em execução; depois que terminar, chame :wait_until_exit() uma vez para confirmar que foi encerrada.
Esta função está disponível a partir da versão 20250705.

Exemplo

-- simula o seguinte comando Shell
-- echo "你好世界" | /usr/bin/gzip -fc | /usr/bin/gzip -dfc

local comp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-fc')    -- cria a tarefa de compressão
local decomp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-dfc') -- cria a tarefa de descompressão

decomp_tsk:set_stdin(comp_tsk:stdout()) -- define o fluxo de entrada da descompressão como a saída da compressão

decomp_tsk:launch() -- inicia a tarefa de descompressão
comp_tsk:launch() -- inicia a tarefa de compressão

comp_tsk:stdin():write("你好世界") -- escreve dados no fluxo de entrada da compressão
comp_tsk:stdin():wclose() -- fecha a extremidade de escrita, indicando que o fluxo de entrada terminou

comp_tsk:wait_until_exit() -- aguarda o término da compressão
decomp_tsk:wait_until_exit() -- aguarda o término da descompressão

nLog(decomp_tsk:stdout():read()) -- lê o fluxo de saída da descompressão e exibe "你好世界"

Exemplo (chamar o Persistence Helper do TrollStore para atualizar)

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')

Exemplo (chamar o TrollStore para instalar/desinstalar um App e reconstruir o cache de ícones)

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

--- instala um App usando o TrollStore
---@param ipapath string caminho do pacote de instalação
---@return string? texto do resultado da instalação; retorna nil em caso de falha
---@return string? mensagem de erro; retorna nil em caso de sucesso
function troll_install(ipapath)
    return _trollstorehelper('install', ipapath)
end

--- desinstala um App instalado pelo TrollStore
---@param bid string identificador do pacote do aplicativo
---@return string? texto do resultado da desinstalação; retorna nil em caso de falha
---@return string? mensagem de erro; retorna nil em caso de sucesso
function troll_uninstall(bid)
    return _trollstorehelper('uninstall', bid)
end

--- o TrollStore reconstrói o cache de ícones; isso pode levar algum tempo
---@return string? texto do resultado da reconstrução; retorna nil em caso de falha
---@return string? mensagem de erro; retorna nil em caso de sucesso
function troll_rebuild_icon_cache()
    return _trollstorehelper('refresh-all')
end

-- chamada de exemplo
nLog(troll_install(XXT_SCRIPTS_PATH..'/TrollDecrypt.tipa')) -- instala o TrollDecrypt
nLog(troll_uninstall('com.fiore.trolldecrypt')) -- desinstala o TrollDecrypt
nLog(troll_rebuild_icon_cache()) -- reconstrói o cache de ícones