stdlib/psort.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)qsort.3     8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdlib/qsort.3,v 1.15 2004/07/02 23:52:12 ru Exp $
  38 .\"
  39 .Dd Nov 25, 2008
  40 .Dt PSORT 3
  41 .Os "Mac OS X"
  42 .Sh NAME
  43 .Nm psort ,
  44 #ifdef UNIFDEF_BLOCKS
  45 .Nm psort_b ,
  46 #endif
  47 .Nm psort_r
  48 .Nd parallel sort functions
  49 .Sh SYNOPSIS
  50 .In stdlib.h
  51 .Ft void
  52 .Fo psort
  53 .Fa "void *base"
  54 .Fa "size_t nel"
  55 .Fa "size_t width"
  56 .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  57 .Fc
  58 #ifdef UNIFDEF_BLOCKS
  59 .Ft void
  60 .Fo psort_b
  61 .Fa "void *base"
  62 .Fa "size_t nel"
  63 .Fa "size_t width"
  64 .Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  65 .Fc
  66 #endif
  67 .Ft void
  68 .Fo psort_r
  69 .Fa "void *base"
  70 .Fa "size_t nel"
  71 .Fa "size_t width"
  72 .Fa "void *thunk"
  73 .Fa "int \*[lp]*compar\*[rp]\*[lp]void *, const void *, const void *\*[rp]"
  74 .Fc
  75 .Sh DESCRIPTION
  76 The
  77 #ifdef UNIFDEF_BLOCKS
  78 .Fn psort ,
  79 .Fn psort_b ,
  80 #else
  81 .Fn psort
  82 #endif
  83 and
  84 .Fn psort_r
  85 functions are parallel sort routines that are drop-in compatible with the
  86 corresponding
  87 .Fn qsort
  88 function (see
  89 .Xr qsort 3
  90 for a description of the arguments).
  91 On multiprocessor machines, multiple threads may be created to simultaneously
  92 perform the sort calculations, resulting in an overall faster sort result.
  93 Overhead in managing the threads limits the maximum speed improvement to
  94 somewhat less that the number of processors available.
  95 For example, on a 4-processor machine, a typical sort on a large array might
  96 result in 3.2 times faster sorting than a regular
  97 .Fn qsort .
  98 .Sh RESTRICTIONS
  99 Because of the multi-threaded nature of the sort, the comparison function
 100 is expected to perform its own synchronization that might be required for
 101 data physically
 102 .Em outside
 103 the two objects passed to the comparison function.
 104 However, no synchronization is required for the two
 105 object themselves, unless some third party is also accessing those objects.
 106 .Pp
 107 Additional memory is temporary allocated to deal with the parallel nature
 108 of the computation.
 109 .Pp
 110 Because of the overhead of maintaining multiple threads, the
 111 .Fn psort
 112 family of routines may choose to just call
 113 .Xr qsort 3
 114 when there is no advantage to parallelizing (for example, when the number of
 115 objects in the array is too small, or only one processor is available).
 116 .Pp
 117 Like
 118 .Xr qsort 3 ,
 119 the sort is not stable.
 120 .Sh RETURN VALUES
 121 The
 122 #ifdef UNIFDEF_BLOCKS
 123 .Fn psort ,
 124 .Fn psort_b
 125 #else
 126 .Fn psort
 127 #endif
 128 and
 129 .Fn psort_r
 130 functions
 131 return no value.
 132 .Sh SEE ALSO
 133 .Xr qsort 3