Module Primus.Jobs

A facility to register and run multiple instances of Primus.

This interface allows only the analysis (specialized) systems.

type action =
  1. | Stop
  2. | 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.

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.

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.