playbook/skills/tsl-api-reference/references/codegen/builtin/process.md

Builtin - 进程

dbglocalcancel(id)

声明：function

注销任务。该功能可以用来终止运行的WEB任务。

参数	类型	说明
id	integer	为dbglocalrunning中返回信息中的id字段以十六进制模式转换为64位整数

返回：bool

示例

范例01：尝试注销指定的本地任务

echo dbglocalcancel(0), "\n";

dbglocalrunning()

声明：function

获得当前所有的任务列表以及堆栈信息，主要用于web等检查在运行中的任务。

返回：array,tablearray

示例

范例01：读取本地任务数量

echo length(dbglocalrunning()), "\n";

sleep(milliseconds)

声明：function

暂停执行。

参数	类型	说明
milliseconds	integer	整数，需要暂停的毫秒数。例如暂停一秒为Sleep(1000)。

返回：nil

示例

范例01：短暂暂停当前脚本

echo "before\n";
sleep(10);
echo "after\n";

sysCloseHandle(handle)

声明：function

关闭一个句柄，如互斥锁，文件句柄等。

参数	类型	说明
handle	integer	整数，句柄编号

返回：bool

示例

范例01：关闭当前进程的临时句柄

handle := sysHandleOfPid(sysProcessId(), 4096, 0);
echo sysCloseHandle(handle), "\n";

sysCmdLine()

声明：function

获得解析器的真实命令行串。

返回：string

示例

范例01：读取当前解析器命令行

echo sysCmdLine(), "\n";

sysCreateMutex(mutex_name)

声明：function

创建一个互斥锁。

参数	类型	说明
mutex_name	string	字符串，互斥锁名称

返回：integer

示例

范例01：创建并释放互斥锁

mutex := sysCreateMutex("tsl-doc-create-mutex");
echo mutex, "\n";
sysReleaseMutex(mutex);

sysErrorMessage(code)

声明：function

返回指定代码表示的系统错误信息。

参数	类型	说明
code	integer	整数，提示代码

返回：string

示例

范例01：读取系统错误码对应的消息

echo sysErrorMessage(2), "\n";

sysExec(prog, cmd_line, startup_dir, wait_exit, var return_code[, wait_ms])

声明：function

创建子进程。wait_exit 为真时等待进程退出并写回退出码；wait_ms 可省略。返回的进程句柄使用后应关闭。

参数	类型	说明
prog	string	可执行文件路径。
cmd_line	string|array	命令行字符串或参数数组。
startup_dir	string|nil	子进程工作目录。
wait_exit	boolean|array	是否等待子进程退出，也可传入管道选项。
return_code	integer|array	写回子进程退出码或管道输出。
wait_ms	integer	可选等待时间，单位为毫秒。

返回：integer

示例

范例01：基本用法

pos := 0;
source := "value := 1;";
writeFile(rwRaw(), "", "child.tsl", pos, length(source), source);
exe_path := sysExecName();
handle := sysExec(exe_path, array(exe_path, "child.tsl"), nil, true, exit_code);
echo handle > 0 and exit_code = 0, "\n";
// 输出：1
sysCloseHandle(handle);
fileDelete("", "child.tsl");

sysexecdeletepipe(process_handle)

声明：function

删除指定进程的管道。参数缺省时，删除默认管道。

参数	类型	说明
process_handle		可选。数值，进程句柄。

返回：bool

示例

范例01：删除当前脚本创建的默认管道

sysExecNewPipe(0);
echo sysExecDeletePipe(), "\n";

sysexecGetenvs()

声明：function

获取子进程的环境变量，应用于Sysexec创建的子进程。

返回：array of string

示例

范例01：读取为子进程准备的环境变量

sysExecSetEnvs(array("TSL_DOC_CHILD=value"), 2);
echo toStn(sysexecGetenvs()), "\n";

sysexecnewpipe(flag)

声明：function

创建Sysexec进程的管道。参数缺省时，默认创建读写管道。创建之后会与第一次被用的进程进行绑定，当有多个Sysexec进程时，可以创建多个管道分别进行读写操作。

参数	类型	说明
flag	integer	可选。整数，控制创建管道的读写属性。Flag转换为二进制时，第0位表示是否可读，第1位表示是否可写。即

返回：bool

示例

范例01：创建并删除默认读写管道

ok := sysExecNewPipe(0);
echo ok, "\n";
sysExecDeletePipe();

sysExecReadPipe([process_handle])

声明：function

读取 SysExec 子进程的管道输出；process_handle 可省略，省略时读取默认管道。

参数	类型	说明
process_handle	integer	可选子进程句柄。

返回：string

示例

范例01：基本用法

pos := 0;
source := 'sleep(100); echo "pipe-output";';
writeFile(rwRaw(), "", "child.tsl", pos, length(source), source);
sysExecNewPipe(0);
exe_path := sysExecName();
handle := sysExec(exe_path, array(exe_path, "child.tsl"), nil, false, exit_code);
output := "";
while output = "" do
begin
    output := sysExecReadPipe(handle);
    sleep(50);
end
echo trim(output), "\n";
// 输出：pipe-output
sysExecDeletePipe(handle);
sysCloseHandle(handle);
fileDelete("", "child.tsl");

sysExecSetEnvs(envs, add_system_env)

声明：function

设置后续 SysExec 子进程使用的环境变量。add_system_env 为 0 时不合并系统环境，1 时追加系统环境，2 时将系统环境置于其后。

参数	类型	说明
envs	array|nil	环境变量数组；nil 清除已设置的子进程环境。
add_system_env	integer	系统环境变量的合并方式：0、1 或 2。

返回：integer

示例

范例01：基本用法

result := sysExecSetEnvs(array("TSL_DOC_CHILD=value"), 2);
envs := sysExecGetEnvs();
echo result = 0 and pos("TSL_DOC_CHILD=value", toStn(envs)) > 0, "\n";
// 输出：1
sysExecSetEnvs(nil, 0);

sysExecWritePipe([process_handle,] content)

声明：function

向 SysExec 子进程的管道写入内容；process_handle 可省略，省略时写入默认管道。成功时返回写入长度，失败时返回 -1。

参数	类型	说明
process_handle	integer	可选子进程句柄。
content	string|binary	请求或管道内容。

返回：integer

示例

范例01：基本用法

sysExecNewPipe(0);
handle := sysExec("/bin/cat", "", nil, false, exit_code);
written := sysExecWritePipe(handle, "pipe-input\n");
sleep(100);
output := sysExecReadPipe(handle);
echo written > 0 and trim(output) = "pipe-input", "\n";
// 输出：1
sysTerminate(0, handle);
sysExecDeletePipe(handle);
sysCloseHandle(handle);

sysgetenv(name)

声明：function

获取当前运行环境下指定环境变量的值。

参数	类型	说明
name	string	字符串，环境变量名。

返回：string

示例

范例01：读取当前进程的环境变量

sysputenv("TSL_DOC_EXAMPLE=value");
echo sysgetenv("TSL_DOC_EXAMPLE"), "\n";

sysGetenvs()

声明：function

获取当前运行环境的全部环境变量串。

返回：array of string

示例

范例01：读取当前进程的环境变量数量

echo length(sysGetenvs()), "\n";

sysGetLastError()

声明：function

获得系统操作的最后一个返回代码。

返回：integer

示例

范例01：读取最近一次系统操作的错误码

echo sysGetLastError(), "\n";

sysGetProcessCmdLine(pid)

声明：function

取得指定进程的命令行；失败时返回空字符串。

参数	类型	说明
pid	integer	进程 ID。

返回：string

示例

范例01：基本用法

echo length(sysGetProcessCmdLine(sysProcessId())) > 0, "\n";
// 输出：1

sysGetProcessCmdLinew(pid)

声明：function

取得指定进程的宽字符串命令行；失败时返回空字符串。

参数	类型	说明
pid	integer	进程 ID。

返回：string

示例

范例01：基本用法

echo length(sysGetProcessCmdLinew(sysProcessId())) > 0, "\n";
// 输出：1

sysGetProcessList()

声明：function

获取当前进程列表信息

返回：array,tablearray

示例

范例01：读取当前进程列表数量

echo length(sysGetProcessList()), "\n";

sysGetProcessListw()

声明：function

获取当前进程列表信息，信息中字符串为宽字节字符串

返回：array,tablearray

示例

范例01：读取宽字符串进程列表数量

echo length(sysGetProcessListw()), "\n";

sysGetProcessNamePath(pid)

声明：function

取得指定进程的可执行文件路径；无法取得路径时返回进程名，失败时返回空字符串。

参数	类型	说明
pid	integer	进程 ID。

返回：string

示例

范例01：基本用法

echo length(sysGetProcessNamePath(sysProcessId())) > 0, "\n";
// 输出：1

sysGetProcessNamePathw(pid)

声明：function

取得指定进程的宽字符串可执行文件路径；失败时返回空字符串。

参数	类型	说明
pid	integer	进程 ID。

返回：string

示例

范例01：基本用法

echo length(sysGetProcessNamePathw(sysProcessId())) > 0, "\n";
// 输出：1

sysGetProcessPriority(var priority[, pid])

声明：function

取得进程优先级并写入 priority。pid 可省略，缺省为当前进程；成功返回 0。

参数	类型	说明
priority	integer	进程优先级；读取时为写回参数。
pid	integer	进程 ID。

返回：integer

示例

范例01：基本用法

result := sysGetProcessPriority(priority);
echo result = 0, "\n";
// 输出：1

sysGetSubProcesses(pid)

声明：function

获得进程的子进程列表

参数	类型	说明
pid	integer	可选。整数，进程ID。未指定时默认获取当前进程内的子进程列表

返回：array,tablearray

示例

范例01：读取当前进程的子进程列表

echo toStn(sysGetSubProcesses(sysProcessId())), "\n";

sysGetThreadName(tid)

声明：function

获取线程名称

参数	类型	说明
tid	integer	可选。整数，线程ID。未指定时默认获取当前线程名称

返回：string

示例

范例01：读取当前线程名称

sysSetThreadName("TslDocExample");
echo sysGetThreadName(), "\n";

sysGetThreadPriority(pri, tid)

声明：function

获取线程优先级

参数	类型	说明
pri	integer	变参，整数，线程优先级
tid	integer	可选。整数，线程ID。未指定时默认获取当前线程优先级

返回：integer

示例

范例01：读取当前线程优先级

status := sysGetThreadPriority(priority);
echo status, ":", priority, "\n";

sysGetThreads(pid)

声明：function

获取进程内的线程列表

参数	类型	说明
pid	integer	可选。整数，进程ID。未指定时默认获取当前进程内的线程列表

返回：array,tablearray

示例

范例01：读取当前进程的线程列表

echo toStn(sysGetThreads(sysProcessId())), "\n";

sysHandleOfPid(pid, rights, inherithandle)

声明：function

Windows上获取进程id对应的句柄，Linux上获取指定文件ID的复制ID。得到的句柄可用函数FAQ：SysCloseHandle进行关闭。

参数	类型	说明
pid	integer	整数，进程ID
rights	integer	可选。整数，设置进程句柄权限，Linux上无效。常见的权限设置值见下表。
inherithandle	integer	可选。布尔值，是否继承，Linux上无效

常见权限值：

值	十进制值	访问权限	可操作范围
0x0010	16	PROCESS_VM_READ	读取进程内存内容
0x0400	1024	PROCESS_QUERY_INFORMATION	查询完整进程信息（令牌、优先级等）
0x1000	4096	PROCESS_QUERY_LIMITED_INFORMATION（缺省值）	仅查询进程基础信息（PID、退出代码等）
0xFFFF	65535	PROCESS_ALL_ACCESS	所有权限（包括终止、内存写入等）

返回：integer

示例

范例01：获取并关闭当前进程句柄

handle := sysHandleOfPid(sysProcessId(), 4096, 0);
echo handle, "\n";
sysCloseHandle(handle);

sysKill(pid[, code])

声明：function

按进程 ID 终止进程。code 可省略，用于指定进程退出码。

参数	类型	说明
pid	integer	进程 ID。
code	integer	可选子进程退出码。

返回：boolean

示例

范例01：基本用法

exe_path := sysExecName();
handle := sysExec(exe_path, array(exe_path, "tsl"), nil, false, exit_code);
pid := sysPidOfHandle(handle);
killed := sysKill(pid, 0);
echo handle > 0 and pid > 0 and killed, "\n";
// 输出：1
sysCloseHandle(handle);

syslinuxkrnlclosemutex(name, isprivate)

声明：function

支持在LINUX上手动删除掉因互斥支持产生的系统信号量以及临时目录的文件

参数	类型	说明
name	string	字符串，互斥锁名称
isprivate	bool	是否私有

返回：any

示例

范例01：清理当前脚本创建的 Linux 互斥锁

mutex_name := "tsl-doc-linux-mutex";
mutex := sysCreateMutex(mutex_name);
sysReleaseMutex(mutex);
echo syslinuxkrnlclosemutex(mutex_name, 0), "\n";

sysParamcount()

声明：function

获得命令行参数个数。（不包括执行的自身.TSL参数）

返回：integer

示例

范例01：读取额外命令行参数数量

echo sysParamcount(), "\n";

sysParamStr(index)

声明：function

获得命令行的指定索引的参数值。

参数	类型	说明
index		整数，命令行参数的索引号。Index=0，返回值为当前天软脚本文件名称；Index>0，返回值为额外传入的命令行参数值（字符串类型）

返回：string

示例

范例01：读取当前脚本文件名参数

echo sysParamStr(0), "\n";

sysPidOfHandle(handle)

声明：function

根据进程句柄获取进程ID。在Linux上，返回和进程句柄值相同的整数

参数	类型	说明
handle	integer	进程句柄

返回：integer

示例

范例01：从当前进程句柄读取进程 ID

handle := sysHandleOfPid(sysProcessId(), 4096, 0);
echo sysPidOfHandle(handle), "\n";
sysCloseHandle(handle);

sysPidOfTid(tid)

声明：function

获取线程所属进程ID

参数	类型	说明
tid	integer	整数，线程ID

返回：integer

示例

范例01：读取当前线程所属的进程 ID

echo sysPidOfTid(sysThreadId()), "\n";

sysPPid(pid)

声明：function

获得进程的父进程ID

参数	类型	说明
pid	integer	可选。整数，进程ID。未指定时默认获取当前进程的父进程ID

返回：integer

示例

范例01：读取当前进程的父进程 ID

echo sysPPid(sysProcessId()), "\n";

sysProcessId()

声明：function

获得运行的进程ID。

返回：integer

示例

范例01：读取当前进程 ID

echo sysProcessId(), "\n";

sysputenv(env_value)

声明：function

设置当前运行环境的指定环境变量的值。

参数	类型	说明
env_value	string	字符串，环境变量名=变量值。

返回：integer

示例

范例01：设置当前进程的环境变量

sysputenv("TSL_DOC_EXAMPLE=value");
echo sysgetenv("TSL_DOC_EXAMPLE"), "\n";

sysReleaseMutex(mutex)

声明：function

释放一个互斥锁。

参数	类型	说明
mutex	integer	整数，互斥锁编号

返回：bool

示例

范例01：释放当前脚本创建的互斥锁

mutex := sysCreateMutex("tsl-doc-release-mutex");
echo sysReleaseMutex(mutex), "\n";

sysSetProcessPriority(priority[, pid])

声明：function

设置进程优先级。pid 可省略，缺省为当前进程；成功返回 0。

参数	类型	说明
priority	integer	进程优先级；读取时为写回参数。
pid	integer	进程 ID。

返回：integer

示例

范例01：基本用法

get_result := sysGetProcessPriority(priority);
set_result := sysSetProcessPriority(priority);
echo get_result = 0 and set_result = 0, "\n";
// 输出：1

sysSetThreadName(name, tid)

声明：function

设置线程名称

参数	类型	说明
name	string	字符串，要设置的名称
tid	integer	可选。整数，线程ID。未指定时默认设置当前线程名称

返回：integer

示例

范例01：设置当前线程名称

status := sysSetThreadName("TslDocExample");
echo status, ":", sysGetThreadName(), "\n";

sysSetThreadPriority(pri, tid)

声明：function

设置线程优先级

参数	类型	说明
pri	integer	线程优先级
tid	integer	可选。线程ID。未指定时默认设置当前线程优先级

返回：integer

示例

范例01：将当前线程保持为原优先级

get_status := sysGetThreadPriority(priority);
if get_status = 0 then
    set_status := sysSetThreadPriority(priority);
else
    set_status := get_status;
echo set_status, "\n";

sysTerminate(ret_code, handle)

声明：function

终止进程。

参数	类型	说明
ret_code	integer	整数，终止进程返回的代码。
handle	integer	整数，终止进程的句柄。缺省为终止自身进程。

返回：any

示例

范例01：终止当前脚本启动的子进程

handle := sysExec("/bin/sleep", "5", nil, false, exit_code);
result := sysTerminate(0, handle);
echo result, "\n";
sysCloseHandle(handle);

sysThreadId()

声明：function

获得运行的线程ID。

返回：integer

示例

范例01：读取当前线程 ID

echo sysThreadId(), "\n";

sysThreadSelf()

声明：function

获取当前程序的线程ID。

返回：integer|int64

示例

范例01：读取当前线程标识

echo sysThreadSelf(), "\n";

sysWaitForMultipleObjects(objects, b_wait_all, wait_ms)

声明：function

等待占有多个对象,例如互斥对象。支持windows和linux的进程

参数	类型	说明
objects	array of integer	一维数字数组，对象句柄数组
b_wait_all	bool	真假，是否等待所有的对象。为真等待所有的，为假则仅需任意一个对象等待成功。
wait_ms	integer	整数，等待的毫秒数，-1则为永远等待。

返回：integer

示例

范例01：等待两个本地子进程结束

handle1 := sysExec("/bin/true", "", nil, false, exit_code1);
handle2 := sysExec("/bin/true", "", nil, false, exit_code2);
wait_result := sysWaitForMultipleObjects(array(handle1, handle2), 1, 5000);
echo wait_result, "\n";
sysCloseHandle(handle1);
sysCloseHandle(handle2);

sysWaitForSingleObject(object, wait_ms)

声明：function

等待占有一个对象,例如互斥对象。支持windows和linux的进程

参数	类型	说明
object	integer	整数，对象名柄
wait_ms	integer	整数，等待的毫秒数，-1则为永远等待。

返回：integer

示例

范例01：等待本地子进程结束

handle := sysExec("/bin/true", "", nil, false, exit_code);
wait_result := sysWaitForSingleObject(handle, 5000);
echo wait_result, "\n";
sysCloseHandle(handle);