文章目录

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

基本工作流程

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

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

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

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

  • 包含有关工作队列的信息的全局变量，例如工作队列在哪个命名空间中运行
  • 工作队列必须处理的序列化工作单元的位置和事件队列
  • 在工作队列完成处理工作单元时创建的完成事件的位置和事件队列
  1. 将工作单元（也称为工作项）添加到工作队列。为此，可以调用​​Queue()​​​ 或​​QueueCallback()​​ 方法。作为参数，传递类方法（或子例程）的名称和任何相应的参数。

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

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

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

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

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

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

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

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

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的数量。

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