lib-job 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793685140/FIN+5.3.1+lib-job 中文整理基于 FIN 5.3.1

导读： 作业管理（已弃用）

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• views
• Overview
• Job Functions
• Scheduled Jobs
• Tuning
• Security
  • def
• jobCancel(handle)
  • supertypes
• jobCurRec(checked: true)
• jobFolioBackup()
• jobFolioCompact()
• jobFolioSnapshot()
• jobIsRunning()
• jobLog(handle)
• jobProgress(percent, msg)
• jobRefreshUser()
• jobRun(expr)
• jobSleep(dur)
• jobStatus(handle)
• jobStatusAll()
  • tags
  • enum
  • src

---

概述（中译）

作业管理（已弃用）

---

API 正文（英文）

docs

Overview • Job Functions • Scheduled Jobs • Tuning • Security

---

tags

job	Background job
jobExpr	Axon expression to execute for job
jobSchedule	Specifies when a job is scheduled using a string format
jobStatus	Current status of a job

---

funcs

jobCancel	Send the cancel message to the job identified by given handle
jobCurRec	If running in the context of a scheduled job then return the job record Dict
jobFolioBackup	Run the folioBackup() function as a background job
jobFolioCompact	This is a no-op
jobFolioSnapshot	Deprecated
jobIsRunning	Is the current context contained by a running job
jobLog	Return the LogRecs logged by the job identified by handle
jobProgress	Update the current job's progress with percent complete and display message for current activity
jobRefreshUser	Refresh the user account used for jobs
jobRun	Run the given expression in the context of a background job
jobSleep	Sleep for the given duration
jobStatus	Return the status for a single job identified by handle
jobStatusAll	Return the status for all the known jobs

---

views

jobs	Manage records used to run background jobs

---

lib job

Overview

The job extension is used to schedule and manage long running computing tasks in the background. The job extension may be used in two ways:

1. any axon expression may be scheduled as a background task using the jobRun() function
2. jobs may be permanently configured and scheduled to run periodically using the job, jobExpr, and jobSchedule tags

NOTE: the job extension is being phased out in favor of the task ext.

Job Functions

The following Axon functions are used to create background tasks:

• jobRun(): kick off an expression in the background
• jobIsRunning(): check if your code is evaluating in context of job
• jobProgress(): used to advance job's progress bar and update users what your job is currently doing

When the jobRun function is called it creates a background job and assigns it an opaque handle string. This handle may be used with functions such as jobStatus and jobLog() to monitor the status of the job.

Typically a function is written to be run in the context of a job. Here is a simple example:

() => do
  echo("TestJob start...")
  10.times(i => do
    jobProgress(i*10, echo("TestJob " + i + "..."))
    jobSleep(1sec)
  end)
  echo("TestJob done!")
end

To test it out create this function and give it a name like myTestJob and then run this expression in the Axon tool:

jobRun(myTestJob)

The function will be scheduled to run, and assuming you don't have other jobs running it should immediately execute on a background thread. The job extension tool will show your job and indicate the progress. The example code above will print messages to stdout every second for ten iterations.

Scheduled Jobs

You can configure scheduled jobs in the job extension tool. Scheduled jobs are recs with these three tags:

• job: marker tag
• jobExpr: the Axon expression to run (typically function name)
• jobSchedule: when to run the job

The job scheduling tag uses a special string format we call a schedule rule:

• one-shot jobs are scheduled to run once at a given date time:
  • onetime 2010-07-04T12:00:00-04:00 New_York
• every jobs are scheduled to run periodically with a given interval:
  • every 15min: run every 15 minutes
  • every 2hr: run every 2 hours
• at jobs are scheduled to run at one or more times of day:
  • at 00:00: run at midnight every day
  • at 9:00,18:00: run at 9am and 6pm every day
• on jobs are scheduled to run only on given days at a given time:
  • on sun at 2:00: run every Sunday at 2am
  • on 1,15 at 12:00: run on the 1st and 15th of each month at noon

Jobs report their status from their last run using the following tags:

• jobLastRuntime: duration of last run
• jobLastStatus: status last run: doneCancel, doneErr, doneOk
• jobLastTime: timestamp when job finished (success or failure)

Job scheduling is based off the jobLastTime tag. If this tag cannot be updated properly, then the job cannot be correctly scheduled. For this reason jobs are not scheduled if the database is not in read-write mode.

Jobs which run every hour or more frequently are called high frequency jobs. High frequency jobs only update their status transiently. This avoids writing job status to disk which is a costly operation. However it means that high frequency jobs will be re-run immediately after every reboot.

If the disabled marker tag is applied to a scheduled job, then it will not automatically run. However it can still be run manually using the jobRun() function.

Tuning

By default, the job extension will run up to 10 concurrent jobs. You can tune this by editing the job ext record and setting maxRunning the desired value.

// set maxRunning to 5
diff(read(ext=="job"), {maxRunning: 5}).commit

The job extension will keep the logs from the previous 20 jobs available in-memory. For jobs that do extensive logging, this can quickly consume heap. You can tune how many job logs are kept in memory by editing the job ext record and setting maxFinished to the desired value.

// set maxFinished to 10
diff(read(ext=="job"), {maxFinished: 10}).commit

Security

Jobs are executed in an axon context using the local user with the username "job". Use the userAllow function to grant specific superuser functions to your jobs. The job user account must not be configured with the "su" role or it will not be used.

If no user is defined by the username "job", then an inferred synthetic user with the "admin" role is used for all evaluations. The synthetic user has its projAccessFilter set to restrict access to the local project only. XQuery to other projects is not available.

Remember that by default all admin users can create/edit jobs. So it is important restrict what can be performed by jobs using the user database.

If testing changes to the job user account, you can call jobRefreshUser() to force an immediate cache refresh.

---

---

def

func:jobCancel

jobCancel(handle)

Send the cancel message to the job identified by given handle. Throw Err if job ext not installed.

Side effects:

• changes job status of given job

---

meta

admin	✓
def	func:jobCancel
is	func
lib	lib:job
name	jobCancel

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobCurRec

jobCurRec(checked: true)

If running in the context of a scheduled job then return the job record Dict. Otherwise raise an error or return null based on the checked flag.

---

meta

def	func:jobCurRec
is	func
lib	lib:job
name	jobCurRec

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobFolioBackup

jobFolioBackup()

Run the folioBackup() function as a background job. Unlike the core function, this function runs synchronously and updates the job progress based on backup progress. Raise an exception if this function is not called while running in a job.

---

meta

admin	✓
def	func:jobFolioBackup
is	func
lib	lib:job
name	jobFolioBackup

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobFolioCompact

jobFolioCompact()

This is a no-op; compaction is no longer required in 3.0

---

meta

admin	✓
def	func:jobFolioCompact
deprecated	✓
is	func
lib	lib:job
name	jobFolioCompact

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobFolioSnapshot

jobFolioSnapshot()

Deprecated: use jobFolioBackup()

---

meta

admin	✓
def	func:jobFolioSnapshot
deprecated	✓
is	func
lib	lib:job
name	jobFolioSnapshot

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobIsRunning

jobIsRunning()

Is the current context contained by a running job.

---

meta

def	func:jobIsRunning
is	func
lib	lib:job
name	jobIsRunning

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobLog

jobLog(handle)

Return the LogRecs logged by the job identified by handle. Throw Err if job ext not installed or handle does map to a valid job. Columns:

• ts: timestamp of log item
• level: err, warn, info, debug
• msg: message of LogRec
• errTrace: dump if there was an exception

---

meta

def	func:jobLog
is	func
lib	lib:job
name	jobLog

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobProgress

jobProgress(percent, msg)

Update the current job's progress with percent complete and display message for current activity. If the current context is not actively running inside a job, this is a no-op.

---

meta

def	func:jobProgress
is	func
lib	lib:job
name	jobProgress

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobRefreshUser

jobRefreshUser()

Refresh the user account used for jobs

---

meta

admin	✓
def	func:jobRefreshUser
is	func
lib	lib:job
name	jobRefreshUser

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobRun

jobRun(expr)

Run the given expression in the context of a background job. If the expression evaluates to a Ref which references a job record, then run that job.

The job is run in the background using admin permissions.

See job.

---

meta

admin	✓
def	func:jobRun
is	func
lib	lib:job
name	jobRun

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobSleep

jobSleep(dur)

Sleep for the given duration. If the current context is not actively running inside a job, this is a no-op.

Side effects:

• pauses the job for the given duration

---

meta

admin	✓
def	func:jobSleep
is	func
lib	lib:job
name	jobSleep

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobStatus

jobStatus(handle)

Return the status for a single job identified by handle. Throw Err if job ext not installed or handle does map to a valid job. Columns:

• handle: unique id for job
• jobStatus: pending, running, cancelling, doneCancel, doneErr, doneOk
• dis: summary display of job
• progress: integer percent complete between 0 and 100
• progressMsg: current progress activity
• started: datetime job was started or null if not run yet
• runtime: duration of job run

---

meta

def	func:jobStatus
is	func
lib	lib:job
name	jobStatus

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:jobStatusAll

jobStatusAll()

Return the status for all the known jobs. Throw Err if job ext not installed. Result grid uses same format as jobStatus.

---

meta

def	func:jobStatusAll
is	func
lib	lib:job
name	jobStatusAll

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

job

Background job

---

meta

def	job
icon	FlagOutlined
is	entity
lib	lib:job
mandatory	✓

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier

---

tags

dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
id	Defines the unique identifier of an entity in system using a ref value type
jobExpr	Axon expression to execute for job
jobSchedule	Specifies when a job is scheduled using a string format
jobStatus	Current status of a job

---

---

def

jobExpr

Axon expression to execute for job

---

meta

def	jobExpr
is	str
lib	lib:job
multiLine	✓
tagOn	job
uiInput	ui::StrInput

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

jobSchedule

Specifies when a job is scheduled using a string format:

onetime 2010-07-04T12:00:00-04:00 New_York
every 15min
every 2hr
at 00:00
at 6:00,20:00
on tue at 16:00
on sat,sun at 02:00
on 1,15 at 02:00

See job.

---

meta

def	jobSchedule
is	str
lib	lib:job
tagOn	job
uiInput	ui::JobScheduleInput

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

jobStatus

Current status of a job

---

meta

def	jobStatus
enum	See below
is	str
lib	lib:job
tagOn	job
transient	✓

---

enum

pending
running
cancelling
doneOk
doneErr
doneCancel

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

view:jobs

Manage records used to run background jobs

---

meta

admin	✓
appName	tools
def	view:jobs
disKey	ui::job
icon	view
is	view
lib	lib:job

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:    { inherit:"tile" }
layout:  { var kind:"Str" defVal:"grid 1x2; 0 0 1 1; 0 1 1 1"}
recs: Trio:
  view:    { inherit:"table" defName:"job" }
  new:     { action:"recNew" }
  edit:    { action:"recEdit" }
  trash:   { action:"recTrash" }
  sep1:    { action:"uiSep" }
  run:     { disKey:"ui::run" action:"jobRun" select }
  sep2:    { action:"uiSep" }
  debug:   { disKey:"ui::debug" action:"jobDebug3" }
  sep3:    { action:"uiSep" }
  enable:  { action:"recEnable" }
  disable: { action:"recDisable" }
  data:    { expr:"readAll(job).sortDis" }
status: Trio:
  view:    { inherit:"table" }
  cancel:  { disKey:"ui::cancel" action:"jobCancel" select tag:"handle" }
  details: { disKey:"ui::details" action:"jobLog" select tag:"handle" }
  data:    { expr:"jobStatusAll()" }