stdlib/psort.3.patch

   1 --- psort.3.orig        2009-05-20 15:59:00.000000000 -0700
   2 +++ psort.3     2009-05-20 16:08:34.000000000 -0700
   3 @@ -36,60 +36,20 @@
   4  .\"     @(#)qsort.3    8.1 (Berkeley) 6/4/93
   5  .\" $FreeBSD: src/lib/libc/stdlib/qsort.3,v 1.15 2004/07/02 23:52:12 ru 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 @@ -97,7 +57,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 @@ -105,7 +65,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 @@ -114,255 +74,60 @@
  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 -#endif
 229 -.Sh RETURN VALUES
 230 -The
 231  #ifdef UNIFDEF_BLOCKS
 232 -.Fn qsort ,
 233 -.Fn qsort_b
 234 +.Fn psort ,
 235 +.Fn psort_b ,
 236  #else
 237 -.Fn qsort
 238 +.Fn psort
 239  #endif
 240  and
 241 -.Fn qsort_r
 242 -functions
 243 -return no value.
 244 -.Pp
 245 -#ifdef UNIFDEF_BLOCKS
 246 -.ds HEAPSORT_B heapsort_b
 247 -.ds MERGESORT_B mergesort_b
 248 -#endif
 249 -.Rv -std heapsort \*[HEAPSORT_B] mergesort \*[MERGESORT_B]
 250 -.Sh ERRORS
 251 +.Fn psort_r
 252 +functions are parallel sort routines that are drop-in compatible with the
 253 +corresponding
 254 +.Fn qsort
 255 +function (see
 256 +.Xr qsort 3
 257 +for a description of the arguments).
 258 +On multiprocessor machines, multiple threads may be created to simultaneously
 259 +perform the sort calculations, resulting in an overall faster sort result.
 260 +Overhead in managing the threads limits the maximum speed improvement to
 261 +somewhat less that the number of processors available.
 262 +For example, on a 4-processor machine, a typical sort on a large array might
 263 +result in 3.2 times faster sorting than a regular
 264 +.Fn qsort .
 265 +.Sh RESTRICTIONS
 266 +Because of the multi-threaded nature of the sort, the comparison function
 267 +is expected to perform its own synchronization that might be required for
 268 +data physically
 269 +.Em outside
 270 +the two objects passed to the comparison function.
 271 +However, no synchronization is required for the two
 272 +object themselves, unless some third party is also accessing those objects.
 273 +.Pp
 274 +Additional memory is temporary allocated to deal with the parallel nature
 275 +of the computation.
 276 +.Pp
 277 +Because of the overhead of maintaining multiple threads, the
 278 +.Fn psort
 279 +family of routines may choose to just call
 280 +.Xr qsort 3
 281 +when there is no advantage to parallelizing (for example, when the number of
 282 +objects in the array is too small, or only one processor is available).
 283 +.Pp
 284 +Like
 285 +.Xr qsort 3 ,
 286 +the sort is not stable.
 287 +.Sh RETURN VALUES
 288  The
 289  #ifdef UNIFDEF_BLOCKS
 290 -.Fn heapsort ,
 291 -.Fn heapsort_b ,
 292 -.Fn mergesort
 293 -and
 294 -.Fn mergesort_b
 295 +.Fn psort ,
 296 +.Fn psort_b
 297  #else
 298 -.Fn heapsort
 299 -and
 300 -.Fn mergesort
 301 -#endif
 302 -functions succeed unless:
 303 -.Bl -tag -width Er
 304 -.It Bq Er EINVAL
 305 -The
 306 -.Fa width
 307 -argument is zero, or,
 308 -the
 309 -.Fa width
 310 -argument to
 311 -.Fn mergesort
 312 -#ifdef UNIFDEF_BLOCKS
 313 -or
 314 -.Fn mergesort_b
 315 +.Fn psort
 316  #endif
 317 -is less than
 318 -.Dq "sizeof(void *) / 2" .
 319 -.It Bq Er ENOMEM
 320 -The
 321 -#ifdef UNIFDEF_BLOCKS
 322 -.Fn heapsort ,
 323 -.Fn heapsort_b ,
 324 -.Fn mergesort
 325 -and
 326 -.Fn mergesort_b
 327 -#else
 328 -.Fn heapsort
 329  and
 330 -.Fn mergesort
 331 -#endif
 332 +.Fn psort_r
 333  functions
 334 -were unable to allocate memory.
 335 -.El
 336 -.Sh COMPATIBILITY
 337 -Previous versions of
 338 -.Fn qsort
 339 -did not permit the comparison routine itself to call
 340 -.Fn qsort 3 .
 341 -This is no longer true.
 342 +return no value.
 343  .Sh SEE ALSO
 344 -.Xr sort 1 ,
 345 -.Xr radixsort 3
 346 -.Rs
 347 -.%A Hoare, C.A.R.
 348 -.%D 1962
 349 -.%T "Quicksort"
 350 -.%J "The Computer Journal"
 351 -.%V 5:1
 352 -.%P pp. 10-15
 353 -.Re
 354 -.Rs
 355 -.%A Williams, J.W.J
 356 -.%D 1964
 357 -.%T "Heapsort"
 358 -.%J "Communications of the ACM"
 359 -.%V 7:1
 360 -.%P pp. 347-348
 361 -.Re
 362 -.Rs
 363 -.%A Knuth, D.E.
 364 -.%D 1968
 365 -.%B "The Art of Computer Programming"
 366 -.%V Vol. 3
 367 -.%T "Sorting and Searching"
 368 -.%P pp. 114-123, 145-149
 369 -.Re
 370 -.Rs
 371 -.%A McIlroy, P.M.
 372 -.%T "Optimistic Sorting and Information Theoretic Complexity"
 373 -.%J "Fourth Annual ACM-SIAM Symposium on Discrete Algorithms"
 374 -.%V January 1992
 375 -.Re
 376 -.Rs
 377 -.%A Bentley, J.L.
 378 -.%A McIlroy, M.D.
 379 -.%T "Engineering a Sort Function"
 380 -.%J "Software--Practice and Experience"
 381 -.%V Vol. 23(11)
 382 -.%P pp. 1249-1265
 383 -.%D November\ 1993
 384 -.Re
 385 -.Sh STANDARDS
 386 -The
 387 -.Fn qsort
 388 -function
 389 -conforms to
 390 -.St -isoC .
 391 +.Xr qsort 3