Skip to main content

Create an Execution Task (sys.task)

Declaration​

task = sys.task(executable_path [, arguments...])

Parameters​

  • executable_path
    String
  • arguments...
    String, optional variadic arguments, defaults to none

Return Value​

  • task
    Execution task object, returns an object for controlling or executing the task

Task Object Methods​

MethodParametersReturn ValueDescription
:launch()Launch the task, runs asynchronously
:wait_until_exit()Synchronously wait for task to finish, blocks all threads until task ends.
:set_stdin(input_stream)Pipe | StringSet the task's input stream. Parameter can be "std", "/dev/null", a file path, or a pipe object. Throws an error if called after task is launched
:stdin()Pipe | StringGet the task's input stream. May return "std", "/dev/null", a file path, or a pipe object
:set_stdout(output_stream)Pipe | StringSet the task's output stream. Parameter can be "std", "/dev/null", a file path, or a pipe object. Throws an error if called after task is launched
:stdout()Pipe | StringGet the task's output stream. May return "std", "/dev/null", a file path, or a pipe object
:set_stderr(error_stream)Pipe | StringSet the task's error stream. Parameter can be "std", "/dev/null", a file path, or a pipe object. Throws an error if called after task is launched
:stderr()Pipe | StringGet the task's error stream. May return "std", "/dev/null", a file path, or a pipe object
:set_work_dir(directory)StringSet the task's working directory. Throws an error if called after task is launched
:work_dir()StringGet the task's working directory
:set_env(environment_variables)TableSet the task's environment variable key-value dictionary. Throws an error if called after task is launched
:env()TableGet the task's environment variable key-value dictionary
:pid()IntegerGet the task's process ID, returns 0 if task has not been launched
:is_running()BooleanCheck if the task is running. Even if :is_running() returns false, you should still call :wait_until_exit() once on the task to prevent zombie processes
:interrupt()BooleanSend SIGINT signal to the task's main process
:terminate()BooleanSend SIGTERM signal to the task's main process
:kill()BooleanSend SIGKILL signal to all processes of the task, kill operation is automatically executed when the task object is garbage collected
:termination_status()IntegerGet the task's termination status, returns nil, error_message if task has not ended
:termination_reason()StringGet the task's termination reason, returns nil, error_message if task has not ended

Pipe Object Methods​

MethodParametersReturn ValueDescription
:read()StringRead available data from the pipe
:write(data)StringWrite data to the pipe
:wclose()Boolean, nil | StringClose the write end of the pipe, returns true on success, false, error_message on failure
:rclose()Boolean, nil | StringClose the read end of the pipe, returns true on success, false, error_message on failure

Description​

Creates an execution task and returns an execution task object
If you don't want to block all threads waiting for the task, you can loop using the task object's :is_running() to check if the task is running. Once it's no longer running, you can call :wait_until_exit() once to confirm the task has ended
Available in versions after 2025-07-05.

Example​

-- Simulate the following Shell command
-- echo "Hello World" | /usr/bin/gzip -fc | /usr/bin/gzip -dfc

local comp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-fc') -- Create compression task
local decomp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-dfc') -- Create decompression task

decomp_tsk:set_stdin(comp_tsk:stdout()) -- Set decompression task's input stream to compression task's output stream

decomp_tsk:launch() -- Launch decompression task
comp_tsk:launch() -- Launch compression task

comp_tsk:stdin():write("Hello World") -- Write data to compression task's input stream
comp_tsk:stdin():wclose() -- Close compression task's input stream write end, indicating input is complete

comp_tsk:wait_until_exit() -- Wait for compression task to finish
decomp_tsk:wait_until_exit() -- Wait for decompression task to finish

nLog(decomp_tsk:stdout():read()) -- Read decompression task's output stream, outputs "Hello World"

Example (Invoke TrollStore Persistence Helper Refresh)​

local persistence_helper_path = app.bundle_path('com.apple.tips')
if not persistence_helper_path then
nLog('Tips.app not detected, please install the Tips app from AppStore first')
return
end
local root_helper_path = persistence_helper_path..'/trollstorehelper'
if file.exists(root_helper_path) ~= 'file' then
nLog('TrollStore Persistence Helper not injected into Tips, please go to TrollStore -> Settings -> Install Persistence Helper and select Tips to inject')
return
end
local tsk = sys.task(root_helper_path, 'refresh')
tsk:launch()
tsk:wait_until_exit()
sys.killall(9, 'SpringBoard', 'backboardd')

Example (Use TrollStore to Install/Uninstall Apps, Rebuild Icon Cache)​

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

--- Install an App using TrollStore
---@param ipapath string Path to the installation package
---@return string? Installation result text, returns nil on failure
---@return string? Error message, returns nil on success
function troll_install(ipapath)
return _trollstorehelper('install', ipapath)
end

--- Uninstall an App installed by TrollStore
---@param bid string App bundle identifier
---@return string? Uninstallation result text, returns nil on failure
---@return string? Error message, returns nil on success
function troll_uninstall(bid)
return _trollstorehelper('uninstall', bid)
end

--- TrollStore rebuild icon cache, may take some time
---@return string? Rebuild result text, returns nil on failure
---@return string? Error message, returns nil on success
function troll_rebuild_icon_cache()
return _trollstorehelper('refresh-all')
end

-- Example calls
nLog(troll_install(XXT_SCRIPTS_PATH..'/TrollDecrypt.tipa')) -- Install TrollDecrypt
nLog(troll_uninstall('com.fiore.trolldecrypt')) -- Uninstall TrollDecrypt
nLog(troll_rebuild_icon_cache()) -- Rebuild icon cache