NAME

kjb_sort - Sorts an array of arbitrary elements.

SYNOPSIS

#include "l/l_sort.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


int kjb_sort
(
	void *array,
	int num_elements,
	size_t element_size,
	int (*cmp_fn)(const void *,const void *),
	int interrupt_action
);

DESCRIPTION

On most systems this function simply wraps a call to qsort(3), based on internal macro symbol KJB_HAVE_QSORT. If that is not possible, then this calls our own implementation of quicksort, which might have a bug (see the note below). (If during testing we discover a system lacking an implementation of qsort, then KJB_HAVE_QSORT should be defined as zero in file l_sys_def.h, in the block corresponding to that operating system. At the time of writing of this comment, all systems we support were believed to have qsort.) Our own implementation is intended to be functionally compatible with qsort. A few extra features are provided at the expense of speed. If the fastest possible sort is required, qsort should be faster (since this is what writers of this sort of routine tend to optimize.). The main functional difference between kjb_sort and qsort is the handling of user interupt which is specified by the last parameter. If the last parameter is USE_CURRENT_ATN_HANDLING, then there is no difference. However a built in handler can be specified with USE_SORT_ATN_HANDLING. With this handler, if the user interupts the sorting, they will be be prompted to whether or not they want to continue. If they respond affirmitively, then the sorting proceeds. Otherwise, the sorting is interrupted, and INTERRUPTED is returned. A third choice for the last parameter is DISABLE_ATN_HANDLING. With this choice, normal attention interupts are ignored during the sort. For sorting on integer keys, the routine int_sort should be faster, since call backs are not required for comparison, although we have not put any effort into making it fast.

RETURNS

This function returns ERROR or NO_ERROR depending upon success. In addition, if USE_SORT_ATN_HANDLING is used, and the sort was interrupted, INTERRUPTED is returned. The locally-implemented sort previously returned the number calls to the comparison required but this is too confusing since we usually just go with qsort these days. If needed, the number of comparisons is available using the function get_last_sort_comparison_count().

TODO

If there is a system that truly requires our homebrew sort, then we should fix the apparent bug that is manifested when running demo program "break_sort.c" in directory lib/l/test/interactive. (We have made a small change, and it is not clear if the problem is still reproducible --- Currently on the mac it seems fine.) The arguments are somewhat self explanitory, but one source of bugs is assuming that the comparison routine can return essentially a boolean answer (i.e., is_greater), but this is not the case. The comparison routine MUST return zero for equality, and postive, or negative as appropriate. The details on when these valences are used is one difference between the home brew version and qsort, and has lead to apparent bugs identified by different results, that were due to an incorrect comparison routine.

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER