117 lines
4.5 KiB
C
117 lines
4.5 KiB
C
|
/* SPDX-License-Identifier: GPL-3.0-or-later
|
||
|
* Copyright © 2023-2024 The TokTok team.
|
||
|
*/
|
||
|
|
||
|
#ifndef C_TOXCORE_TOXCORE_SORT_H
|
||
|
#define C_TOXCORE_TOXCORE_SORT_H
|
||
|
|
||
|
#include <stdbool.h>
|
||
|
#include <stdint.h>
|
||
|
|
||
|
#include "attributes.h"
|
||
|
|
||
|
#ifdef __cplusplus
|
||
|
extern "C" {
|
||
|
#endif
|
||
|
|
||
|
/** @brief Compare elements with a less-than ordering: `a < b`. */
|
||
|
typedef bool sort_less_cb(const void *object, const void *a, const void *b);
|
||
|
/** @brief Get element from array at index. */
|
||
|
typedef const void *sort_get_cb(const void *arr, uint32_t index);
|
||
|
/** @brief Set element in array at index to new value (perform copy). */
|
||
|
typedef void sort_set_cb(void *arr, uint32_t index, const void *val);
|
||
|
/** @brief Get a sub-array at an index of a given size (mutable pointer).
|
||
|
*
|
||
|
* Used to index in the temporary array allocated by `sort_alloc_cb` and get
|
||
|
* a sub-array for working memory.
|
||
|
*/
|
||
|
typedef void *sort_subarr_cb(void *arr, uint32_t index, uint32_t size);
|
||
|
/** @brief Allocate a new array of the element type.
|
||
|
*
|
||
|
* @param size The array size in elements of type T (not byte size). This value
|
||
|
* is always exactly the input array size as passed to `merge_sort`.
|
||
|
*/
|
||
|
typedef void *sort_alloc_cb(const void *object, uint32_t size);
|
||
|
/** @brief Free the element type array. */
|
||
|
typedef void sort_delete_cb(const void *object, void *arr, uint32_t size);
|
||
|
|
||
|
/** @brief Virtual function table for getting/setting elements in an array and
|
||
|
* comparing them.
|
||
|
*
|
||
|
* Only the `less`, `alloc`, and `delete` functions get a `this`-pointer. We
|
||
|
* assume that indexing in an array doesn't need any other information than the
|
||
|
* array itself.
|
||
|
*
|
||
|
* For now, the `this`-pointer is const, because we assume sorting doesn't need
|
||
|
* to mutate any state, but if necessary that can be changed in the future.
|
||
|
*/
|
||
|
typedef struct Sort_Funcs {
|
||
|
sort_less_cb *less_callback;
|
||
|
sort_get_cb *get_callback;
|
||
|
sort_set_cb *set_callback;
|
||
|
sort_subarr_cb *subarr_callback;
|
||
|
sort_alloc_cb *alloc_callback;
|
||
|
sort_delete_cb *delete_callback;
|
||
|
} Sort_Funcs;
|
||
|
|
||
|
/** @brief Non-recursive merge sort function to sort `arr[0...arr_size-1]`.
|
||
|
*
|
||
|
* Avoids `memcpy` and avoids treating elements as byte arrays. Instead, uses
|
||
|
* callbacks to index in arrays and copy elements. This makes it quite a bit
|
||
|
* slower than `qsort`, but works with elements that require special care when
|
||
|
* being copied (e.g. if they are part of a graph or other data structure that
|
||
|
* with pointers or other invariants).
|
||
|
*
|
||
|
* This function actually uses insertion sort for small arrays (up to 16
|
||
|
* elements), which is faster than merge sort for small arrays, especially
|
||
|
* when mostly sorted (a common use case in toxcore).
|
||
|
*
|
||
|
* Allocates a single temporary array with the provided alloc callback, and
|
||
|
* frees it at the end. This is significantly faster than an in-place
|
||
|
* implementation.
|
||
|
*
|
||
|
* Complexity:
|
||
|
* - Space: `O(n) where n = array_size`.
|
||
|
* - Time: `O(n * log n) where n = array_size`.
|
||
|
*
|
||
|
* Compared to `qsort`, this is about 60-70% slower for large arrays. For small
|
||
|
* arrays (up to 16 elements), it's about 50% faster than `qsort`.
|
||
|
*
|
||
|
* @param[in,out] arr An array of type T.
|
||
|
* @param arr_size Number of elements in @p arr (count, not byte size).
|
||
|
* @param[in] object Comparator object.
|
||
|
* @param[in] funcs Callback struct for elements of type T.
|
||
|
*/
|
||
|
non_null()
|
||
|
bool merge_sort(void *arr, uint32_t arr_size, const void *object, const Sort_Funcs *funcs);
|
||
|
|
||
|
/**
|
||
|
* @brief Merge sort like above but with a pre-allocated buffer.
|
||
|
*
|
||
|
* This function is the same as `merge_sort` but uses a pre-allocated buffer
|
||
|
* for temporary storage. This can be useful if the caller wants to avoid
|
||
|
* dynamic memory allocation.
|
||
|
*
|
||
|
* This function is 1-2% faster than `merge_sort` for small arrays up to 1000
|
||
|
* elements, and about 5-10% faster for large arrays (2000+ elements).
|
||
|
*
|
||
|
* The main upside is that `alloc` and `delete` callbacks don't need to be
|
||
|
* implemented, and the caller can use a stack-allocated buffer.
|
||
|
*
|
||
|
* @param[in,out] arr An array of type T.
|
||
|
* @param arr_size Number of elements in @p arr (count, not byte size).
|
||
|
* @param[in,out] tmp A buffer of size `tmp_size` for temporary storage.
|
||
|
* @param tmp_size Number of elements in @p tmp (count, not byte size). Must be
|
||
|
* at least as large as `arr_size`.
|
||
|
* @param[in] object Comparator object.
|
||
|
* @param[in] funcs Callback struct for elements of type T.
|
||
|
*/
|
||
|
non_null()
|
||
|
void merge_sort_with_buf(void *arr, uint32_t arr_size, void *tmp, uint32_t tmp_size, const void *object, const Sort_Funcs *funcs);
|
||
|
|
||
|
#ifdef __cplusplus
|
||
|
} /* extern "C" */
|
||
|
#endif
|
||
|
|
||
|
#endif /* C_TOXCORE_TOXCORE_SORT_H */
|