第十九章 使用工作队列管理器（二）

基本工作流程

可以通过执行以下步骤来使用工作队列管理器：

1. 将ObjectScript 代码划分为工作单元，这些工作单元是满足特定要求的类方法或子例程。
2. 创建一个工作队列，它是 %SYSTEM.WorkMgr 类的一个实例。为此，请调用 %SYSTEM.WorkMgr 类的 %New() 方法。该方法返回一个工作队列。

可以指定要使用的并行worker jobs的数量，也可以使用默认值，这取决于机器和操作系统。此外，如果已创建类别，则可以指定应从中获取job的类别。

创建工作队列时，工作队列管理器会创建以下工件：

• 包含有关工作队列的信息的全局变量，例如工作队列在哪个命名空间中运行
• 工作队列必须处理的序列化工作单元的位置和事件队列
• 在工作队列完成处理工作单元时创建的完成事件的位置和事件队列

3. 将工作单元（也称为工作项）添加到工作队列。为此，可以调用 Queue() 或 QueueCallback() 方法。作为参数，传递类方法（或子例程）的名称和任何相应的参数。

对添加到队列的项目立即开始处理。

如果队列中的项目多于队列可用的worker jobs，则job会竞争清空队列。例如，如果有 100 个项目和四个job，则每个job从队列的头部移除一个项目，处理它，然后返回到队列的头部以移除并处理另一个项目。这种模式一直持续到队列为空。

工作队列管理器在运行工作项时使用调用者的安全上下文。

当对工作项进行排队时，工作队列管理器会执行以下任务：

• 序列化构成工作单元的参数、安全上下文和类方法或子例程，然后将序列化的数据插入到列出与工作队列关联的工作单元的全局global中
• 发出工作队列上的事件信号
• 如果需要额外的worker jobs并且可用于处理工作单元，则导致worker jobs附加到工作队列并减少可worker jobs的数量

4. 等待工作完成。为此，可以调用工作队列的 WaitForComplete() 方法。

工作队列管理器然后执行以下任务：

• 等待完成事件
• 向终端显示工作负载指标等输出
• 收集与工作单元相关的任何错误
• 如果使用 QueueCallback() 方法将工作单元添加到工作队列，则运行回调代码

5. 根据应用程序继续处理。

以下示例显示了这些基本步骤：

ClassMethod WorkJob(){
    
	s queue = ##class(%SYSTEM.WorkMgr).%New() 
	for i = 1 : 1 : filelist.Count() {
    
		s sc = queue.Queue("..Load", filelist.GetAt(i))
		if $$$ISERR(sc) {
     
		    ret sc
		}
	}
	s sc = queue.WaitForComplete()
	if $$$ISERR(sc) {
     
		ret sc
	}
}

该代码初始化工作队列管理器，然后遍历文件列表。对于每个文件，代码添加一个加载文件的工作队列项。添加所有工作队列项后，代码等待工作完成。

注意： %SYSTEM.WorkMgr 类支持更复杂的工作流以及本文档后面描述的方法。

基本方法

要完成上一节中描述的步骤，可以使用 %SYSTEM.WorkMgr 类的以下三个方法：

%New()

classmethod %New(qspec As %String = "", numberjobs As %Integer, category) as WorkMgr

创建、初始化并返回一个工作队列，它是可用于执行并行处理的 %SYSTEM.WorkMgr 类的一个实例。该方法接受以下参数：

• qspec - 影响在此工作队列中运行的代码的一串编译器标志和限定符。
• numberjobs - 在此工作队列中使用的最大并行worker jobs数。默认值取决于机器和操作系统的特性。
• category - 提供要在此工作队列中使用的 worker jobs的类别的名称。

系统在创建时不会将任何工作任务分配给队列。只有在将工作单元添加到工作队列后，才会分配工作人员作业。

Queue()

method Queue(work As %String, args... As %String) as %Status

将工作单元添加到工作队列。该方法接受以下参数：

• work

要执行的代码。通常，代码应该返回一个 %Status 值来指示成功或失败。

如果代码返回 %Status 值，可以使用以下语法：

• ##class(Classname).ClassMethod 用于类方法，其中 Classname 是类的完全限定名称，ClassMethod 是方法的名称。如果方法在同一个类中，可以使用语法 ..ClassMethod，如示例中所示。
• $$entry^rtn 用于子例程，其中 entry 是子例程的名称，rtn 是例程的名称。

如果代码未返回 %Status 值，请改用以下语法：

• =##class(Classname).ClassMethod 用于类方法（或 =..ClassMethod 如果方法在同一个类中）

• entry^rtn 子程序

• args

类方法或子例程的参数的逗号分隔列表。要将多维数组作为参数传递，请照常在该参数前面加上句点，以便通过引用传递。

在这些参数中传递的数据的大小应该相对较小，以充分利用框架。要传递大量信息，请使用全局而不是参数。

当对工作单元进行排队时，系统会一次分配一个工作程序作业，最多为创建工作队列时指定的 numberjobs 值或最多为默认值。此外，调用者的安全上下文被记录下来，每个工作项都在该安全上下文中运行。

WaitForComplete()

method WaitForComplete(qspec As %String, errorlog As %String) as %Status

等待工作队列完成所有项目，然后返回一个 %Status 值来指示成功或失败。 %Status 值包含来自工作项返回的所有 %Status 值的信息。该方法接受以下参数：

• qspec - 一串编译器标志和限定符。
• errorlog - 任何错误信息的字符串，作为输出返回。

工作队列的属性

每个工作队列（或 %SYSTEM.WorkMgr 的实例）都具有以下属性：

NumWorkers

分配给工作队列的worker jobs数。

NumActiveWorkers

当前活跃worker的数量。

此外，工作队列所属类别的属性决定了工作队列的行为。