eclass/multiprocessing.eclass

   1 # Copyright 1999-2014 Gentoo Foundation
   2 # Distributed under the terms of the GNU General Public License v2
   3 # $Id$
   4
   5 # @ECLASS: multiprocessing.eclass
   6 # @MAINTAINER:
   7 # base-system@gentoo.org
   8 # @AUTHOR:
   9 # Brian Harring <ferringb@gentoo.org>
  10 # Mike Frysinger <vapier@gentoo.org>
  11 # @BLURB: parallelization with bash (wtf?)
  12 # @DESCRIPTION:
  13 # The multiprocessing eclass contains a suite of functions that allow ebuilds
  14 # to quickly run things in parallel using shell code.
  15 #
  16 # It has two modes: pre-fork and post-fork.  If you don't want to dive into any
  17 # more nuts & bolts, just use the pre-fork mode.  For main threads that mostly
  18 # spawn children and then wait for them to finish, use the pre-fork mode.  For
  19 # main threads that do a bit of processing themselves, use the post-fork mode.
  20 # You may mix & match them for longer computation loops.
  21 # @EXAMPLE:
  22 #
  23 # @CODE
  24 # # First initialize things:
  25 # multijob_init
  26 #
  27 # # Then hash a bunch of files in parallel:
  28 # for n in {0..20} ; do
  29 #       multijob_child_init md5sum data.${n} > data.${n}
  30 # done
  31 #
  32 # # Then wait for all the children to finish:
  33 # multijob_finish
  34 # @CODE
  35
  36 if [[ -z ${_MULTIPROCESSING_ECLASS} ]]; then
  37 _MULTIPROCESSING_ECLASS=1
  38
  39 # @FUNCTION: bashpid
  40 # @DESCRIPTION:
  41 # Return the process id of the current sub shell.  This is to support bash
  42 # versions older than 4.0 that lack $BASHPID support natively.  Simply do:
  43 # echo ${BASHPID:-$(bashpid)}
  44 #
  45 # Note: Using this func in any other way than the one above is not supported.
  46 bashpid() {
  47         # Running bashpid plainly will return incorrect results.  This func must
  48         # be run in a subshell of the current subshell to get the right pid.
  49         # i.e. This will show the wrong value:
  50         #   bashpid
  51         # But this will show the right value:
  52         #   (bashpid)
  53         sh -c 'echo ${PPID}'
  54 }
  55
  56 # @FUNCTION: makeopts_jobs
  57 # @USAGE: [${MAKEOPTS}]
  58 # @DESCRIPTION:
  59 # Searches the arguments (defaults to ${MAKEOPTS}) and extracts the jobs number
  60 # specified therein.  Useful for running non-make tools in parallel too.
  61 # i.e. if the user has MAKEOPTS=-j9, this will echo "9" -- we can't return the
  62 # number as bash normalizes it to [0, 255].  If the flags haven't specified a
  63 # -j flag, then "1" is shown as that is the default `make` uses.  Since there's
  64 # no way to represent infinity, we return 999 if the user has -j without a number.
  65 makeopts_jobs() {
  66         [[ $# -eq 0 ]] && set -- ${MAKEOPTS}
  67         # This assumes the first .* will be more greedy than the second .*
  68         # since POSIX doesn't specify a non-greedy match (i.e. ".*?").
  69         local jobs=$(echo " $* " | sed -r -n \
  70                 -e 's:.*[[:space:]](-j|--jobs[=[:space:]])[[:space:]]*([0-9]+).*:\2:p' \
  71                 -e 's:.*[[:space:]](-j|--jobs)[[:space:]].*:999:p')
  72         echo ${jobs:-1}
  73 }
  74
  75 # @FUNCTION: makeopts_loadavg
  76 # @USAGE: [${MAKEOPTS}]
  77 # @DESCRIPTION:
  78 # Searches the arguments (defaults to ${MAKEOPTS}) and extracts the value set
  79 # for load-average. For make and ninja based builds this will mean new jobs are
  80 # not only limited by the jobs-value, but also by the current load - which might
  81 # get excessive due to I/O and not just due to CPU load.
  82 # Be aware that the returned number might be a floating-point number. Test
  83 # whether your software supports that.
  84 makeopts_loadavg() {
  85         [[ $# -eq 0 ]] && set -- ${MAKEOPTS}
  86         # This assumes the first .* will be more greedy than the second .*
  87         # since POSIX doesn't specify a non-greedy match (i.e. ".*?").
  88         local lavg=$(echo " $* " | sed -r -n \
  89                 -e 's:.*[[:space:]](-l|--(load-average|max-load)[=[:space:]])[[:space:]]*([0-9]+|[0-9]+\.[0-9]+).*:\3:p' \
  90                 -e 's:.*[[:space:]](-l|--(load-average|max-load))[[:space:]].*:999:p')
  91         # Default to 999 since the default is to not use a load limit.
  92         echo ${lavg:-999}
  93 }
  94
  95 # @FUNCTION: multijob_init
  96 # @USAGE: [${MAKEOPTS}]
  97 # @DESCRIPTION:
  98 # Setup the environment for executing code in parallel.
  99 # You must call this before any other multijob function.
 100 multijob_init() {
 101         # When something goes wrong, try to wait for all the children so we
 102         # don't leave any zombies around.
 103         has wait ${EBUILD_DEATH_HOOKS} || EBUILD_DEATH_HOOKS+=" wait "
 104
 105         # Setup a pipe for children to write their pids to when they finish.
 106         # We have to allocate two fd's because POSIX has undefined behavior
 107         # when you open a FIFO for simultaneous read/write. #487056
 108         local pipe="${T}/multijob.pipe"
 109         mkfifo -m 600 "${pipe}"
 110         redirect_alloc_fd mj_write_fd "${pipe}"
 111         redirect_alloc_fd mj_read_fd "${pipe}"
 112         rm -f "${pipe}"
 113
 114         # See how many children we can fork based on the user's settings.
 115         mj_max_jobs=$(makeopts_jobs "$@")
 116         mj_num_jobs=0
 117 }
 118
 119 # @FUNCTION: multijob_child_init
 120 # @USAGE: [--pre|--post] [command to run in background]
 121 # @DESCRIPTION:
 122 # This function has two forms.  You can use it to execute a simple command
 123 # in the background (and it takes care of everything else), or you must
 124 # call this first thing in your forked child process.
 125 #
 126 # The --pre/--post options allow you to select the child generation mode.
 127 #
 128 # @CODE
 129 # # 1st form: pass the command line as arguments:
 130 # multijob_child_init ls /dev
 131 # # Or if you want to use pre/post fork modes:
 132 # multijob_child_init --pre ls /dev
 133 # multijob_child_init --post ls /dev
 134 #
 135 # # 2nd form: execute multiple stuff in the background (post fork):
 136 # (
 137 # multijob_child_init
 138 # out=`ls`
 139 # if echo "${out}" | grep foo ; then
 140 #       echo "YEAH"
 141 # fi
 142 # ) &
 143 # multijob_post_fork
 144 #
 145 # # 2nd form: execute multiple stuff in the background (pre fork):
 146 # multijob_pre_fork
 147 # (
 148 # multijob_child_init
 149 # out=`ls`
 150 # if echo "${out}" | grep foo ; then
 151 #       echo "YEAH"
 152 # fi
 153 # ) &
 154 # @CODE
 155 multijob_child_init() {
 156         local mode="pre"
 157         case $1 in
 158         --pre)  mode="pre" ; shift ;;
 159         --post) mode="post"; shift ;;
 160         esac
 161
 162         if [[ $# -eq 0 ]] ; then
 163                 trap 'echo ${BASHPID:-$(bashpid)} $? >&'${mj_write_fd} EXIT
 164                 trap 'exit 1' INT TERM
 165         else
 166                 local ret
 167                 [[ ${mode} == "pre" ]] && { multijob_pre_fork; ret=$?; }
 168                 ( multijob_child_init ; "$@" ) &
 169                 [[ ${mode} == "post" ]] && { multijob_post_fork; ret=$?; }
 170                 return ${ret}
 171         fi
 172 }
 173
 174 # @FUNCTION: _multijob_fork
 175 # @INTERNAL
 176 # @DESCRIPTION:
 177 # Do the actual book keeping.
 178 _multijob_fork() {
 179         [[ $# -eq 1 ]] || die "incorrect number of arguments"
 180
 181         local ret=0
 182         [[ $1 == "post" ]] && : $(( ++mj_num_jobs ))
 183         if [[ ${mj_num_jobs} -ge ${mj_max_jobs} ]] ; then
 184                 multijob_finish_one
 185                 ret=$?
 186         fi
 187         [[ $1 == "pre" ]] && : $(( ++mj_num_jobs ))
 188         return ${ret}
 189 }
 190
 191 # @FUNCTION: multijob_pre_fork
 192 # @DESCRIPTION:
 193 # You must call this in the parent process before forking a child process.
 194 # If the parallel limit has been hit, it will wait for one child to finish
 195 # and return its exit status.
 196 multijob_pre_fork() { _multijob_fork pre "$@" ; }
 197
 198 # @FUNCTION: multijob_post_fork
 199 # @DESCRIPTION:
 200 # You must call this in the parent process after forking a child process.
 201 # If the parallel limit has been hit, it will wait for one child to finish
 202 # and return its exit status.
 203 multijob_post_fork() { _multijob_fork post "$@" ; }
 204
 205 # @FUNCTION: multijob_finish_one
 206 # @DESCRIPTION:
 207 # Wait for a single process to exit and return its exit code.
 208 multijob_finish_one() {
 209         [[ $# -eq 0 ]] || die "${FUNCNAME} takes no arguments"
 210
 211         local pid ret
 212         read -r -u ${mj_read_fd} pid ret || die
 213         : $(( --mj_num_jobs ))
 214         return ${ret}
 215 }
 216
 217 # @FUNCTION: multijob_finish
 218 # @DESCRIPTION:
 219 # Wait for all pending processes to exit and return the bitwise or
 220 # of all their exit codes.
 221 multijob_finish() {
 222         local ret=0
 223         while [[ ${mj_num_jobs} -gt 0 ]] ; do
 224                 multijob_finish_one
 225                 : $(( ret |= $? ))
 226         done
 227         # Let bash clean up its internal child tracking state.
 228         wait
 229
 230         # Do this after reaping all the children.
 231         [[ $# -eq 0 ]] || die "${FUNCNAME} takes no arguments"
 232
 233         # No need to hook anymore.
 234         EBUILD_DEATH_HOOKS=${EBUILD_DEATH_HOOKS/ wait / }
 235
 236         return ${ret}
 237 }
 238
 239 # @FUNCTION: redirect_alloc_fd
 240 # @USAGE: <var> <file> [redirection]
 241 # @DESCRIPTION:
 242 # Find a free fd and redirect the specified file via it.  Store the new
 243 # fd in the specified variable.  Useful for the cases where we don't care
 244 # about the exact fd #.
 245 redirect_alloc_fd() {
 246         local var=$1 file=$2 redir=${3:-"<>"}
 247
 248         # Make sure /dev/fd is sane on Linux hosts. #479656
 249         if [[ ! -L /dev/fd && ${CBUILD} == *linux* ]] ; then
 250                 eerror "You're missing a /dev/fd symlink to /proc/self/fd."
 251                 eerror "Please fix the symlink and check your boot scripts (udev/etc...)."
 252                 die "/dev/fd is broken"
 253         fi
 254
 255         if [[ $(( (BASH_VERSINFO[0] << 8) + BASH_VERSINFO[1] )) -ge $(( (4 << 8) + 1 )) ]] ; then
 256                 # Newer bash provides this functionality.
 257                 eval "exec {${var}}${redir}'${file}'"
 258         else
 259                 # Need to provide the functionality ourselves.
 260                 local fd=10
 261                 while :; do
 262                         # Make sure the fd isn't open.  It could be a char device,
 263                         # or a symlink (possibly broken) to something else.
 264                         if [[ ! -e /dev/fd/${fd} ]] && [[ ! -L /dev/fd/${fd} ]] ; then
 265                                 eval "exec ${fd}${redir}'${file}'" && break
 266                         fi
 267                         [[ ${fd} -gt 1024 ]] && die 'could not locate a free temp fd !?'
 268                         : $(( ++fd ))
 269                 done
 270                 : $(( ${var} = fd ))
 271         fi
 272 }
 273
 274 fi