stdlib/psort.3.patch

   1 --- psort.3.orig        2010-10-07 21:34:52.000000000 -0700
   2 +++ psort.3     2010-10-07 21:45:11.000000000 -0700
   3 @@ -32,60 +32,20 @@
   4  .\"     @(#)qsort.3    8.1 (Berkeley) 6/4/93
   5  .\" $FreeBSD: src/lib/libc/stdlib/qsort.3,v 1.17 2007/01/09 00:28:10 imp Exp $
   6  .\"
   7 -.Dd September 30, 2003
   8 -.Dt QSORT 3
   9 -.Os
  10 +.Dd Nov 25, 2008
  11 +.Dt PSORT 3
  12 +.Os "Mac OS X"
  13  .Sh NAME
  14 -.Nm heapsort ,
  15 +.Nm psort ,
  16  #ifdef UNIFDEF_BLOCKS
  17 -.Nm heapsort_b ,
  18 +.Nm psort_b ,
  19  #endif
  20 -.Nm mergesort ,
  21 -#ifdef UNIFDEF_BLOCKS
  22 -.Nm mergesort_b ,
  23 -#endif
  24 -.Nm qsort ,
  25 -#ifdef UNIFDEF_BLOCKS
  26 -.Nm qsort_b ,
  27 -#endif
  28 -.Nm qsort_r
  29 -.Nd sort functions
  30 +.Nm psort_r
  31 +.Nd parallel sort functions
  32  .Sh SYNOPSIS
  33  .In stdlib.h
  34 -.Ft int
  35 -.Fo heapsort
  36 -.Fa "void *base"
  37 -.Fa "size_t nel"
  38 -.Fa "size_t width"
  39 -.Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  40 -.Fc
  41 -#ifdef UNIFDEF_BLOCKS
  42 -.Ft int
  43 -.Fo heapsort_b
  44 -.Fa "void *base"
  45 -.Fa "size_t nel"
  46 -.Fa "size_t width"
  47 -.Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  48 -.Fc
  49 -#endif
  50 -.Ft int
  51 -.Fo mergesort
  52 -.Fa "void *base"
  53 -.Fa "size_t nel"
  54 -.Fa "size_t width"
  55 -.Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  56 -.Fc
  57 -#ifdef UNIFDEF_BLOCKS
  58 -.Ft int
  59 -.Fo mergesort_b
  60 -.Fa "void *base"
  61 -.Fa "size_t nel"
  62 -.Fa "size_t width"
  63 -.Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  64 -.Fc
  65 -#endif
  66  .Ft void
  67 -.Fo qsort
  68 +.Fo psort
  69  .Fa "void *base"
  70  .Fa "size_t nel"
  71  .Fa "size_t width"
  72 @@ -93,7 +53,7 @@
  73  .Fc
  74  #ifdef UNIFDEF_BLOCKS
  75  .Ft void
  76 -.Fo qsort_b
  77 +.Fo psort_b
  78  .Fa "void *base"
  79  .Fa "size_t nel"
  80  .Fa "size_t width"
  81 @@ -101,7 +61,7 @@
  82  .Fc
  83  #endif
  84  .Ft void
  85 -.Fo qsort_r
  86 +.Fo psort_r
  87  .Fa "void *base"
  88  .Fa "size_t nel"
  89  .Fa "size_t width"
  90 @@ -110,210 +70,63 @@
  91  .Fc
  92  .Sh DESCRIPTION
  93  The
  94 -.Fn qsort
  95 -function is a modified partition-exchange sort, or quicksort.
  96 -The
  97 -.Fn heapsort
  98 -function is a modified selection sort.
  99 -The
 100 -.Fn mergesort
 101 -function is a modified merge sort with exponential search,
 102 -intended for sorting data with pre-existing order.
 103 -.Pp
 104 -The
 105 -.Fn qsort
 106 -and
 107 -.Fn heapsort
 108 -functions sort an array of
 109 -.Fa nel
 110 -objects, the initial member of which is pointed to by
 111 -.Fa base .
 112 -The size of each object is specified by
 113 -.Fa width .
 114 -The
 115 -.Fn mergesort
 116 -function
 117 -behaves similarly, but
 118 -.Em requires
 119 -that
 120 -.Fa width
 121 -be greater than or equal to
 122 -.Dq "sizeof(void *) / 2" .
 123 -.Pp
 124 -The contents of the array
 125 -.Fa base
 126 -are sorted in ascending order according to
 127 -a comparison function pointed to by
 128 -.Fa compar ,
 129 -which requires two arguments pointing to the objects being
 130 -compared.
 131 -.Pp
 132 -The comparison function must return an integer less than, equal to, or
 133 -greater than zero if the first argument is considered to be respectively
 134 -less than, equal to, or greater than the second.
 135 -.Pp
 136 -The
 137 -.Fn qsort_r
 138 -function behaves identically to
 139 -.Fn qsort ,
 140 -except that it takes an additional argument,
 141 -.Fa thunk ,
 142 -which is passed unchanged as the first argument to function pointed to
 143 -.Fa compar .
 144 -This allows the comparison function to access additional
 145 -data without using global variables, and thus
 146 -.Fn qsort_r
 147 -is suitable for use in functions which must be reentrant.
 148 -.Pp
 149 -The algorithms implemented by
 150 -.Fn qsort ,
 151 -.Fn qsort_r ,
 152 -and
 153 -.Fn heapsort
 154 -are
 155 -.Em not
 156 -stable; that is, if two members compare as equal, their order in
 157 -the sorted array is undefined.
 158 -The
 159 -.Fn mergesort
 160 -algorithm is stable.
 161 -.Pp
 162 -The
 163 -.Fn qsort
 164 -and
 165 -.Fn qsort_r
 166 -functions are an implementation of C.A.R.
 167 -Hoare's
 168 -.Dq quicksort
 169 -algorithm,
 170 -a variant of partition-exchange sorting; in particular, see
 171 -.An D.E. Knuth Ns 's
 172 -.%T "Algorithm Q" .
 173 -.Sy Quicksort
 174 -takes O N lg N average time.
 175 -This implementation uses median selection to avoid its
 176 -O N**2 worst-case behavior.
 177 -.Pp
 178 -The
 179 -.Fn heapsort
 180 -function is an implementation of
 181 -.An "J.W.J. William" Ns 's
 182 -.Dq heapsort
 183 -algorithm,
 184 -a variant of selection sorting; in particular, see
 185 -.An "D.E. Knuth" Ns 's
 186 -.%T "Algorithm H" .
 187 -.Sy Heapsort
 188 -takes O N lg N worst-case time.
 189 -Its
 190 -.Em only
 191 -advantage over
 192 -.Fn qsort
 193 -is that it uses almost no additional memory; while
 194 -.Fn qsort
 195 -does not allocate memory, it is implemented using recursion.
 196 -.Pp
 197 -The function
 198 -.Fn mergesort
 199 -requires additional memory of size
 200 -.Fa nel *
 201 -.Fa width
 202 -bytes; it should be used only when space is not at a premium.
 203 -The
 204 -.Fn mergesort
 205 -function
 206 -is optimized for data with pre-existing order; its worst case
 207 -time is O N lg N; its best case is O N.
 208 -.Pp
 209 -Normally,
 210 -.Fn qsort
 211 -is faster than
 212 -.Fn mergesort
 213 -which is faster than
 214 -.Fn heapsort .
 215 -Memory availability and pre-existing order in the data can make this
 216 -untrue.
 217  #ifdef UNIFDEF_BLOCKS
 218 -.Pp
 219 -The
 220 -.Fn heapsort_b ,
 221 -.Fn mergesort_b ,
 222 -and
 223 -.Fn qsort_b
 224 -routines are like the corresponding routines without the _b suffix, expect
 225 -that the
 226 -.Fa compar
 227 -callback is a block pointer instead of a function pointer.
 228 +.Fn psort ,
 229 +.Fn psort_b ,
 230 +#else
 231 +.Fn psort
 232  #endif
 233 +and
 234 +.Fn psort_r
 235 +functions are parallel sort routines that are drop-in compatible with the
 236 +corresponding
 237 +.Fn qsort
 238 +function (see
 239 +.Xr qsort 3
 240 +for a description of the arguments).
 241 +On multiprocessor machines, multiple threads may be created to simultaneously
 242 +perform the sort calculations, resulting in an overall faster sort result.
 243 +Overhead in managing the threads limits the maximum speed improvement to
 244 +somewhat less that the number of processors available.
 245 +For example, on a 4-processor machine, a typical sort on a large array might
 246 +result in 3.2 times faster sorting than a regular
 247 +.Fn qsort .
 248 +.Sh RESTRICTIONS
 249 +Because of the multi-threaded nature of the sort, the comparison function
 250 +is expected to perform its own synchronization that might be required for
 251 +data physically
 252 +.Em outside
 253 +the two objects passed to the comparison function.
 254 +However, no synchronization is required for the two
 255 +object themselves, unless some third party is also accessing those objects.
 256 +.Pp
 257 +Additional memory is temporary allocated to deal with the parallel nature
 258 +of the computation.
 259 +.Pp
 260 +Because of the overhead of maintaining multiple threads, the
 261 +.Fn psort
 262 +family of routines may choose to just call
 263 +.Xr qsort 3
 264 +when there is no advantage to parallelizing (for example, when the number of
 265 +objects in the array is too small, or only one processor is available).
 266 +.Pp
 267 +Like
 268 +.Xr qsort 3 ,
 269 +the sort is not stable.
 270  .Sh RETURN VALUES
 271  The
 272  #ifdef UNIFDEF_BLOCKS
 273 -.Fn qsort ,
 274 -.Fn qsort_b
 275 +.Fn psort ,
 276 +.Fn psort_b
 277  #else
 278 -.Fn qsort
 279 +.Fn psort
 280  #endif
 281  and
 282 -.Fn qsort_r
 283 +.Fn psort_r
 284  functions
 285  return no value.
 286 -.Pp
 287 -#ifdef UNIFDEF_BLOCKS
 288 -.ds HEAPSORT_B heapsort_b
 289 -.ds MERGESORT_B mergesort_b
 290 -#endif
 291 -.Rv -std heapsort \*[HEAPSORT_B] mergesort \*[MERGESORT_B]
 292 -.Sh COMPATIBILITY
 293 -Previous versions of
 294 -.Fn qsort
 295 -did not permit the comparison routine itself to call
 296 -.Fn qsort 3 .
 297 -This is no longer true.
 298 -.Sh ERRORS
 299 -The
 300 -#ifdef UNIFDEF_BLOCKS
 301 -.Fn heapsort ,
 302 -.Fn heapsort_b ,
 303 -.Fn mergesort ,
 304 -and
 305 -.Fn mergesort_b
 306 -#else
 307 -.Fn heapsort
 308 -and
 309 -.Fn mergesort
 310 -#endif
 311 -functions succeed unless:
 312 -.Bl -tag -width Er
 313 -.It Bq Er EINVAL
 314 -The
 315 -.Fa width
 316 -argument is zero, or,
 317 -the
 318 -.Fa width
 319 -argument to
 320 -.Fn mergesort
 321 -#ifdef UNIFDEF_BLOCKS
 322 -or
 323 -.Fn mergesort_b
 324 -#endif
 325 -is less than
 326 -.Dq "sizeof(void *) / 2" .
 327 -.It Bq Er ENOMEM
 328 -The
 329 -#ifdef UNIFDEF_BLOCKS
 330 -.Fn heapsort ,
 331 -.Fn heapsort_b ,
 332 -.Fn mergesort ,
 333 -or
 334 -.Fn mergesort_b
 335 -#else
 336 -.Fn heapsort
 337 -or
 338 -.Fn mergesort
 339 -#endif
 340 -functions
 341 -were unable to allocate memory.
 342 -.El
 343 +.Sh SEE ALSO
 344 +.Xr qsort 3
 345  .Sh SEE ALSO
 346  .Xr sort 1 ,
 347  .Xr radixsort 3