Jobs (bap-primus.Bap_primus.Std.Primus.Jobs)

type action =

| Stop
| Continue

an action to take after each job.

type result

the final result of running the job queue.

val enqueue : 
  ?name:string ->
  ?desc:string ->
  ?envp:string array ->
  ?args:string array ->
  ?init:unit Machine.Make(Bap_knowledge.Knowledge).t ->
  ?fini:unit Machine.Make(Bap_knowledge.Knowledge).t ->
  ?start:unit Machine.Make(Bap_knowledge.Knowledge).t ->
  system ->
  unit

enqueue system creates a new job and enqueues it for future run.

parameter name
a short name of the job for logging (defaults to unnamed)

parameter desc
a short description of the job task (defaults to "")

parameter envp
the array of environment variables

parameter argv
the array of commandline arguments

parameter init
runs after machine boots

parameter start
runs after machine is initialized

val pending : unit -> int

pending () is the number of jobs still waiting to be run.

val run : 
  ?on_failure:(Job.t -> Bap_knowledge.Knowledge.conflict -> result -> action) ->
  ?on_success:
    (Job.t -> exit_status -> Bap_knowledge.Knowledge.state -> result -> action) ->
  Bap.Std.project ->
  Bap_knowledge.Knowledge.state ->
  result

run project state runs until there are no more jobs queued or until explicitly stopped.

The project and state values are used as the initial static program representation and knowledge base.

Every time a job is finised either on_success or on_conflict is called. These callbacks shall return either Stop or Continue. If either returns Stop then run also stops even if there are more jobs in the queue (the jobs are not cleared, so pending () might be non-zero).

Both of the callbacks return Continue by default.

parameter on_conflict
is called as on_conflict sys conflict when the system sys failes to converge and stops with the knowledge conflict. The returned value should indicate what to do next.

parameter on_success
is called as on_success sys status kb when the system sys terminates without knowledge conflicts with the exit status and the knowledge stored in kb. The returned value prescribes what to do next.
Note that the job queue could be extended during analysis, the run function will execute all jobs in the FIFO order, unless explicitly stopped.

val knowledge : result -> Bap_knowledge.Knowledge.state

knowledge result is the knowledge obtained from running the jobs.

val project : result -> Bap.Std.project

project result is the final static representation of program.

val failures : result -> (Job.t * Bap_knowledge.Knowledge.conflict) list

failures result is the list of failed jobs.

Each failed is a pair of the job and and the description of the conflict that prevented system from convering.

The failures are specified in the order in which they happened.

val finished : result -> Job.t list

finished result is the final list of jobs that were run in the order in which they were run.