/* -------------------------------------------------------------------------
 *
 * tuplesort.h
 *	  Generalized tuple sorting routines.
 *
 * This module handles sorting of heap tuples, index tuples, or single
 * Datums (and could easily support other kinds of sortable objects,
 * if necessary).  It works efficiently for both small and large amounts
 * of data.  Small amounts are sorted in-memory using qsort().	Large
 * amounts are sorted using temporary files and a standard external sort
 * algorithm.
 *
 * Portions Copyright (c) 1996-2012, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/tuplesort.h
 *
 * -------------------------------------------------------------------------
 */
#ifndef TUPLESORT_H
#define TUPLESORT_H

#include "access/itup.h"
#include "executor/tuptable.h"
#include "fmgr.h"
#include "utils/relcache.h"
#include "utils/tuplestore.h"

/* Tuplesortstate is an opaque type whose details are not known outside
 * tuplesort.c.
 */
typedef struct Tuplesortstate Tuplesortstate;

/*
 * We provide multiple interfaces to what is essentially the same code,
 * since different callers have different data to be sorted and want to
 * specify the sort key information differently.  There are two APIs for
 * sorting HeapTuples and two more for sorting IndexTuples.  Yet another
 * API supports sorting bare Datums.
 *
 * The "heap" API actually stores/sorts MinimalTuples, which means it doesn't
 * preserve the system columns (tuple identity and transaction visibility
 * info).  The sort keys are specified by column numbers within the tuples
 * and sort operator OIDs.	We save some cycles by passing and returning the
 * tuples in TupleTableSlots, rather than forming actual HeapTuples (which'd
 * have to be converted to MinimalTuples).	This API works well for sorts
 * executed as parts of plan trees.
 *
 * The "cluster" API stores/sorts full HeapTuples including all visibility
 * info. The sort keys are specified by reference to a btree index that is
 * defined on the relation to be sorted.  Note that putheaptuple/getheaptuple
 * go with this API, not the "begin_heap" one!
 *
 * The "index_btree" API stores/sorts IndexTuples (preserving all their
 * header fields).	The sort keys are specified by a btree index definition.
 *
 * The "index_hash" API is similar to index_btree, but the tuples are
 * actually sorted by their hash codes not the raw data.
 */

extern Tuplesortstate* tuplesort_begin_heap(TupleDesc tupDesc, int nkeys, AttrNumber* attNums, Oid* sortOperators,
    Oid* sortCollations, const bool* nullsFirstFlags, int64 workMem, bool randomAccess, int64 maxMem = 0,
    int planId = 0, int dop = 1);
extern Tuplesortstate* tuplesort_begin_cluster(
    TupleDesc tupDesc, Relation indexRel, int workMem, bool randomAccess, int maxMem);
extern Tuplesortstate* tuplesort_begin_index_btree(
    Relation indexRel, bool enforceUnique, int workMem, bool randomAccess, int maxMem);
extern Tuplesortstate* tuplesort_begin_index_hash(
    Relation indexRel, uint32 hash_mask, int workMem, bool randomAccess, int maxMem);
extern Tuplesortstate* tuplesort_begin_datum(
    Oid datumType, Oid sortOperator, Oid sortCollation, bool nullsFirstFlag, int workMem, bool randomAccess);
#ifdef PGXC
extern void tuplesort_puttupleslotontape(Tuplesortstate* state, TupleTableSlot* slot);
extern void tuplesort_remoteread_end(Tuplesortstate* state);
#endif

extern void tuplesort_set_bound(Tuplesortstate* state, int64 bound);

extern void tuplesort_puttupleslot(Tuplesortstate* state, TupleTableSlot* slot);
extern void tuplesort_putheaptuple(Tuplesortstate* state, HeapTuple tup);
extern void tuplesort_putindextuplevalues(
    Tuplesortstate* state, Relation rel, ItemPointer self, Datum* values, const bool* isnull);
extern void tuplesort_putdatum(Tuplesortstate* state, Datum val, bool isNull);

extern void tuplesort_performsort(Tuplesortstate* state);

extern bool tuplesort_gettupleslot(Tuplesortstate* state, bool forward, TupleTableSlot* slot, Datum* abbrev);
extern bool tuplesort_gettupleslot_into_tuplestore(
    Tuplesortstate* state, bool forward, TupleTableSlot* slot, Datum* abbrev, Tuplestorestate* tstate);
extern HeapTuple tuplesort_getheaptuple(Tuplesortstate* state, bool forward, bool* should_free);
extern IndexTuple tuplesort_getindextuple(Tuplesortstate* state, bool forward, bool* should_free);
extern bool tuplesort_getdatum(Tuplesortstate* state, bool forward, Datum* val, bool* isNull);

extern void tuplesort_end(Tuplesortstate* state);

extern void tuplesort_get_stats(Tuplesortstate* state, int* sortMethodId, int* spaceTypeId, long* spaceUsed);

extern int tuplesort_merge_order(double allowedMem);

/*
 * These routines may only be called if randomAccess was specified 'true'.
 * Likewise, backwards scan in gettuple/getdatum is only allowed if
 * randomAccess was specified.
 */

extern void tuplesort_rescan(Tuplesortstate* state);
extern void tuplesort_markpos(Tuplesortstate* state);
extern void tuplesort_restorepos(Tuplesortstate* state);

extern void sort_count(Tuplesortstate* state);

extern int64 tuplesort_get_avgwidth(Tuplesortstate* state);
extern bool tuplesort_get_busy_status(Tuplesortstate* state);
extern int tuplesort_get_spread_num(Tuplesortstate* state);
extern bool tuplesort_skiptuples(Tuplesortstate* state, int64 ntuples, bool forward);
extern void UpdateUniqueSQLSortStats(Tuplesortstate* state, TimestampTz* start_time);

/*
 * Return the int64 value of tuplesortstate->peakMemorySize
 */
extern int64 tuplesort_get_peak_memory(Tuplesortstate* state);

#endif /* TUPLESORT_H */