README.md

   1 jobflow by rofl0r
   2 =================
   3
   4 this program is inspired by the functionality of GNU parallel, but tries
   5 to keep low overhead and follow the UNIX philosophy of doing one thing well.
   6
   7 how it works
   8 ------------
   9
  10 basically, it works by processing stdin, launching one process per line.
  11 the actual line can be passed to the started program as an argv.
  12 this allows for easy parallelization of standard unix tasks.
  13
  14 it is possible to save the current processed line, so when the task is killed
  15 it can be continued later.
  16
  17 example usage
  18 -------------
  19
  20 you have a list of things, and a tool that processes a single thing.
  21
  22     cat things.list | jobflow -threads=8 -exec ./mytask {}
  23
  24     seq 100 | jobflow -threads=100 -exec echo {}
  25
  26     cat urls.txt | jobflow -threads=32 -exec wget {}
  27
  28     find . -name '*.bmp' | jobflow -threads=8 -exec bmp2jpeg {.}.bmp {.}.jpg
  29
  30 run jobflow without arguments to see a list of possible command line options,
  31 and argument permutations.
  32
  33 Comparison with GNU parallel
  34 ----------------------------
  35
  36 GNU parallel is written in perl, which has the following disadvantages:
  37 - requires a perl installation
  38   even though most people already have perl installed anyway, installing it
  39   just for this purpose requires up to 50 MB storage (and potentially up to
  40   several hours of time to compile it from source on slow devices)
  41 - requires a lot of time on startup (parsing sources, etc)
  42 - requires a lot of memory (typically between 5-60 MB)
  43 - some versions of perl's garbage collector are buggy and leak memory
  44
  45 jobflow OTOH is written in C, which has numerous advantages.
  46 - once compiled to a tiny static binary, can be used without 3rd party stuff
  47 - very little and constant memory usage (typically a few KB)
  48 - no startup overhead
  49 - much higher execution speed
  50
  51 apart from the chosen language and related performance differences, the
  52 following other differences exist between GNU parallel and jobflow:
  53
  54 + supports rlimits passed to started processes
  55 - doesn't support ssh (usage of remote cpus)
  56 - doesn't support all kinds of argument permutations:
  57   while GNU parallel has a rich set of options to permute the input,
  58   this doesn't adhere to the UNIX philosophy.
  59   jobflow can achieve the same result by passing the unmodified input
  60   to a user-created script that does the required permutations with other
  61   standard tools.
  62
  63 BUILD
  64 -----
  65
  66 grab the latest release tarball from the releases page, and just run `make`.
  67 it contains all library dependencies.
  68 https://github.com/rofl0r/jobflow/releases
  69
  70 instructions to build from git:
  71
  72     cd /tmp
  73     mkdir jobflow-0000
  74     cd jobflow-0000/
  75     git clone https://github.com/rofl0r/libulz lib
  76     git clone https://github.com/rofl0r/jobflow
  77     git clone https://github.com/rofl0r/rcb
  78     export PATH=$PATH:/tmp/jobflow-0000/rcb
  79     ln -s /tmp/jobflow-0000/rcb/rcb.pl /tmp/jobflow-0000/rcb/rcb
  80     cd jobflow
  81     CC="gcc -static" CFLAGS="-O0 -g -Wall -Wextra" rcb jobflow.c
  82