toast_internals.h File Reference

#include "access/toast_compression.h"
#include "storage/lockdefs.h"
#include "utils/relcache.h"
#include "utils/snapshot.h"

Include dependency graph for toast_internals.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	toast_compress_header

Macros
#define	TOAST_COMPRESS_EXTSIZE(ptr)    (((toast_compress_header *) (ptr))->tcinfo & VARLENA_EXTSIZE_MASK)
#define	TOAST_COMPRESS_METHOD(ptr)    (((toast_compress_header *) (ptr))->tcinfo >> VARLENA_EXTSIZE_BITS)
#define	TOAST_COMPRESS_SET_SIZE_AND_COMPRESS_METHOD(ptr, len, cm_method)

Typedefs
typedef struct toast_compress_header	toast_compress_header

Functions
Datum	toast_compress_datum (Datum value, char cmethod)
Oid	toast_get_valid_index (Oid toastoid, LOCKMODE lock)
void	toast_delete_datum (Relation rel, Datum value, bool is_speculative)
Datum	toast_save_datum (Relation rel, Datum value, struct varlena *oldexternal, int options)
int	toast_open_indexes (Relation toastrel, LOCKMODE lock, Relation **toastidxs, int *num_indexes)
void	toast_close_indexes (Relation *toastidxs, int num_indexes, LOCKMODE lock)
Snapshot	get_toast_snapshot (void)

Macro Definition Documentation

TOAST_COMPRESS_EXTSIZE

#define TOAST_COMPRESS_EXTSIZE

(

ptr

)

(((toast_compress_header *) (ptr))->tcinfo & VARLENA_EXTSIZE_MASK)

Definition at line 34 of file toast_internals.h.

TOAST_COMPRESS_METHOD

#define TOAST_COMPRESS_METHOD

(

ptr

)

(((toast_compress_header *) (ptr))->tcinfo >> VARLENA_EXTSIZE_BITS)

Definition at line 36 of file toast_internals.h.

TOAST_COMPRESS_SET_SIZE_AND_COMPRESS_METHOD

#define TOAST_COMPRESS_SET_SIZE_AND_COMPRESS_METHOD	(		ptr,
			len,
			cm_method
	)

Value:

    do { \
        Assert((len) > 0 && (len) <= VARLENA_EXTSIZE_MASK); \
        Assert((cm_method) == TOAST_PGLZ_COMPRESSION_ID || \
               (cm_method) == TOAST_LZ4_COMPRESSION_ID); \
        ((toast_compress_header *) (ptr))->tcinfo = \
            (len) | ((uint32) (cm_method) << VARLENA_EXTSIZE_BITS); \
    } while (0)

Definition at line 39 of file toast_internals.h.

Typedef Documentation

toast_compress_header

typedef struct toast_compress_header toast_compress_header

Function Documentation

get_toast_snapshot()

Snapshot get_toast_snapshot

(

void

)

Definition at line 638 of file toast_internals.c.

{
    /*
     * We cannot directly check that detoasting happens in the same
     * transaction that originally fetched the toast pointer, but at least
     * check that the session has some active snapshots. It might not if, for
     * example, a procedure fetches a toasted value into a local variable,
     * commits, and then tries to detoast the value. Such coding is unsafe,
     * because once we commit there is nothing to prevent the toast data from
     * being deleted. (This is not very much protection, because in many
     * scenarios the procedure would have already created a new transaction
     * snapshot, preventing us from detecting the problem. But it's better
     * than nothing.)
     */
    if (!HaveRegisteredOrActiveSnapshot())
        elog(ERROR, "cannot fetch toast data without an active snapshot");
 
    return &SnapshotToastData;
}

References elog, ERROR, HaveRegisteredOrActiveSnapshot(), and SnapshotToastData.

Referenced by check_toasted_attribute(), heap_fetch_toast_slice(), and toast_delete_datum().

toast_close_indexes()

void toast_close_indexes	(	Relation *	toastidxs,
		int	num_indexes,
		LOCKMODE	lock
	)

Definition at line 621 of file toast_internals.c.

{
    int         i;
 
    /* Close relations and clean up things */
    for (i = 0; i < num_indexes; i++)
        index_close(toastidxs[i], lock);
    pfree(toastidxs);
}

References i, index_close(), and pfree().

Referenced by heap_fetch_toast_slice(), toast_delete_datum(), toast_get_valid_index(), toast_save_datum(), toastrel_valueid_exists(), and verify_heapam().

toast_compress_datum()

Datum toast_compress_datum	(	Datum	value,
		char	cmethod
	)

Definition at line 46 of file toast_internals.c.

{
    struct varlena *tmp = NULL;
    int32       valsize;
    ToastCompressionId cmid = TOAST_INVALID_COMPRESSION_ID;
 
    Assert(!VARATT_IS_EXTERNAL(DatumGetPointer(value)));
    Assert(!VARATT_IS_COMPRESSED(DatumGetPointer(value)));
 
    valsize = VARSIZE_ANY_EXHDR(DatumGetPointer(value));
 
    /* If the compression method is not valid, use the current default */
    if (!CompressionMethodIsValid(cmethod))
        cmethod = default_toast_compression;
 
    /*
     * Call appropriate compression routine for the compression method.
     */
    switch (cmethod)
    {
        case TOAST_PGLZ_COMPRESSION:
            tmp = pglz_compress_datum((const struct varlena *) value);
            cmid = TOAST_PGLZ_COMPRESSION_ID;
            break;
        case TOAST_LZ4_COMPRESSION:
            tmp = lz4_compress_datum((const struct varlena *) value);
            cmid = TOAST_LZ4_COMPRESSION_ID;
            break;
        default:
            elog(ERROR, "invalid compression method %c", cmethod);
    }
 
    if (tmp == NULL)
        return PointerGetDatum(NULL);
 
    /*
     * We recheck the actual size even if compression reports success, because
     * it might be satisfied with having saved as little as one byte in the
     * compressed data --- which could turn into a net loss once you consider
     * header and alignment padding.  Worst case, the compressed format might
     * require three padding bytes (plus header, which is included in
     * VARSIZE(tmp)), whereas the uncompressed format would take only one
     * header byte and no padding if the value is short enough.  So we insist
     * on a savings of more than 2 bytes to ensure we have a gain.
     */
    if (VARSIZE(tmp) < valsize - 2)
    {
        /* successful compression */
        Assert(cmid != TOAST_INVALID_COMPRESSION_ID);
        TOAST_COMPRESS_SET_SIZE_AND_COMPRESS_METHOD(tmp, valsize, cmid);
        return PointerGetDatum(tmp);
    }
    else
    {
        /* incompressible data */
        pfree(tmp);
        return PointerGetDatum(NULL);
    }
}

References Assert, CompressionMethodIsValid, DatumGetPointer(), default_toast_compression, elog, ERROR, lz4_compress_datum(), pfree(), pglz_compress_datum(), PointerGetDatum(), TOAST_COMPRESS_SET_SIZE_AND_COMPRESS_METHOD, TOAST_INVALID_COMPRESSION_ID, TOAST_LZ4_COMPRESSION, TOAST_LZ4_COMPRESSION_ID, TOAST_PGLZ_COMPRESSION, TOAST_PGLZ_COMPRESSION_ID, value, VARATT_IS_COMPRESSED, VARATT_IS_EXTERNAL, VARSIZE, and VARSIZE_ANY_EXHDR.

Referenced by brin_form_tuple(), index_form_tuple_context(), and toast_tuple_try_compression().

toast_delete_datum()

void toast_delete_datum	(	Relation	rel,
		Datum	value,
		bool	is_speculative
	)

Definition at line 385 of file toast_internals.c.

{
    struct varlena *attr = (struct varlena *) DatumGetPointer(value);
    struct varatt_external toast_pointer;
    Relation    toastrel;
    Relation   *toastidxs;
    ScanKeyData toastkey;
    SysScanDesc toastscan;
    HeapTuple   toasttup;
    int         num_indexes;
    int         validIndex;
 
    if (!VARATT_IS_EXTERNAL_ONDISK(attr))
        return;
 
    /* Must copy to access aligned fields */
    VARATT_EXTERNAL_GET_POINTER(toast_pointer, attr);
 
    /*
     * Open the toast relation and its indexes
     */
    toastrel = table_open(toast_pointer.va_toastrelid, RowExclusiveLock);
 
    /* Fetch valid relation used for process */
    validIndex = toast_open_indexes(toastrel,
                                    RowExclusiveLock,
                                    &toastidxs,
                                    &num_indexes);
 
    /*
     * Setup a scan key to find chunks with matching va_valueid
     */
    ScanKeyInit(&toastkey,
                (AttrNumber) 1,
                BTEqualStrategyNumber, F_OIDEQ,
                ObjectIdGetDatum(toast_pointer.va_valueid));
 
    /*
     * Find all the chunks.  (We don't actually care whether we see them in
     * sequence or not, but since we've already locked the index we might as
     * well use systable_beginscan_ordered.)
     */
    toastscan = systable_beginscan_ordered(toastrel, toastidxs[validIndex],
                                           get_toast_snapshot(), 1, &toastkey);
    while ((toasttup = systable_getnext_ordered(toastscan, ForwardScanDirection)) != NULL)
    {
        /*
         * Have a chunk, delete it
         */
        if (is_speculative)
            heap_abort_speculative(toastrel, &toasttup->t_self);
        else
            simple_heap_delete(toastrel, &toasttup->t_self);
    }
 
    /*
     * End scan and close relations but keep the lock until commit, so as a
     * concurrent reindex done directly on the toast relation would be able to
     * wait for this transaction.
     */
    systable_endscan_ordered(toastscan);
    toast_close_indexes(toastidxs, num_indexes, NoLock);
    table_close(toastrel, NoLock);
}

References BTEqualStrategyNumber, DatumGetPointer(), ForwardScanDirection, get_toast_snapshot(), heap_abort_speculative(), NoLock, ObjectIdGetDatum(), RowExclusiveLock, ScanKeyInit(), simple_heap_delete(), systable_beginscan_ordered(), systable_endscan_ordered(), systable_getnext_ordered(), HeapTupleData::t_self, table_close(), table_open(), toast_close_indexes(), toast_open_indexes(), varatt_external::va_toastrelid, varatt_external::va_valueid, value, VARATT_EXTERNAL_GET_POINTER, and VARATT_IS_EXTERNAL_ONDISK.

Referenced by toast_delete_external(), and toast_tuple_cleanup().

toast_get_valid_index()

Oid toast_get_valid_index	(	Oid	toastoid,
		LOCKMODE	lock
	)

Definition at line 528 of file toast_internals.c.

{
    int         num_indexes;
    int         validIndex;
    Oid         validIndexOid;
    Relation   *toastidxs;
    Relation    toastrel;
 
    /* Open the toast relation */
    toastrel = table_open(toastoid, lock);
 
    /* Look for the valid index of the toast relation */
    validIndex = toast_open_indexes(toastrel,
                                    lock,
                                    &toastidxs,
                                    &num_indexes);
    validIndexOid = RelationGetRelid(toastidxs[validIndex]);
 
    /* Close the toast relation and all its indexes */
    toast_close_indexes(toastidxs, num_indexes, NoLock);
    table_close(toastrel, NoLock);
 
    return validIndexOid;
}

References NoLock, RelationGetRelid, table_close(), table_open(), toast_close_indexes(), and toast_open_indexes().

Referenced by finish_heap_swap(), and swap_relation_files().

toast_open_indexes()

int toast_open_indexes	(	Relation	toastrel,
		LOCKMODE	lock,
		Relation **	toastidxs,
		int *	num_indexes
	)

Definition at line 562 of file toast_internals.c.

{
    int         i = 0;
    int         res = 0;
    bool        found = false;
    List       *indexlist;
    ListCell   *lc;
 
    /* Get index list of the toast relation */
    indexlist = RelationGetIndexList(toastrel);
    Assert(indexlist != NIL);
 
    *num_indexes = list_length(indexlist);
 
    /* Open all the index relations */
    *toastidxs = (Relation *) palloc(*num_indexes * sizeof(Relation));
    foreach(lc, indexlist)
        (*toastidxs)[i++] = index_open(lfirst_oid(lc), lock);
 
    /* Fetch the first valid index in list */
    for (i = 0; i < *num_indexes; i++)
    {
        Relation    toastidx = (*toastidxs)[i];
 
        if (toastidx->rd_index->indisvalid)
        {
            res = i;
            found = true;
            break;
        }
    }
 
    /*
     * Free index list, not necessary anymore as relations are opened and a
     * valid index has been found.
     */
    list_free(indexlist);
 
    /*
     * The toast relation should have one valid index, so something is going
     * wrong if there is nothing.
     */
    if (!found)
        elog(ERROR, "no valid index found for toast relation with Oid %u",
             RelationGetRelid(toastrel));
 
    return res;
}

References Assert, elog, ERROR, i, index_open(), lfirst_oid, list_free(), list_length(), NIL, palloc(), RelationData::rd_index, RelationGetIndexList(), RelationGetRelid, and res.

Referenced by heap_fetch_toast_slice(), toast_delete_datum(), toast_get_valid_index(), toast_save_datum(), toastrel_valueid_exists(), and verify_heapam().

toast_save_datum()

Datum toast_save_datum	(	Relation	rel,
		Datum	value,
		struct varlena *	oldexternal,
		int	options
	)

Definition at line 119 of file toast_internals.c.

{
    Relation    toastrel;
    Relation   *toastidxs;
    HeapTuple   toasttup;
    TupleDesc   toasttupDesc;
    Datum       t_values[3];
    bool        t_isnull[3];
    CommandId   mycid = GetCurrentCommandId(true);
    struct varlena *result;
    struct varatt_external toast_pointer;
    union
    {
        struct varlena hdr;
        /* this is to make the union big enough for a chunk: */
        char        data[TOAST_MAX_CHUNK_SIZE + VARHDRSZ];
        /* ensure union is aligned well enough: */
        int32       align_it;
    }           chunk_data;
    int32       chunk_size;
    int32       chunk_seq = 0;
    char       *data_p;
    int32       data_todo;
    Pointer     dval = DatumGetPointer(value);
    int         num_indexes;
    int         validIndex;
 
    Assert(!VARATT_IS_EXTERNAL(value));
 
    /*
     * Open the toast relation and its indexes.  We can use the index to check
     * uniqueness of the OID we assign to the toasted item, even though it has
     * additional columns besides OID.
     */
    toastrel = table_open(rel->rd_rel->reltoastrelid, RowExclusiveLock);
    toasttupDesc = toastrel->rd_att;
 
    /* Open all the toast indexes and look for the valid one */
    validIndex = toast_open_indexes(toastrel,
                                    RowExclusiveLock,
                                    &toastidxs,
                                    &num_indexes);
 
    /*
     * Get the data pointer and length, and compute va_rawsize and va_extinfo.
     *
     * va_rawsize is the size of the equivalent fully uncompressed datum, so
     * we have to adjust for short headers.
     *
     * va_extinfo stored the actual size of the data payload in the toast
     * records and the compression method in first 2 bits if data is
     * compressed.
     */
    if (VARATT_IS_SHORT(dval))
    {
        data_p = VARDATA_SHORT(dval);
        data_todo = VARSIZE_SHORT(dval) - VARHDRSZ_SHORT;
        toast_pointer.va_rawsize = data_todo + VARHDRSZ;    /* as if not short */
        toast_pointer.va_extinfo = data_todo;
    }
    else if (VARATT_IS_COMPRESSED(dval))
    {
        data_p = VARDATA(dval);
        data_todo = VARSIZE(dval) - VARHDRSZ;
        /* rawsize in a compressed datum is just the size of the payload */
        toast_pointer.va_rawsize = VARDATA_COMPRESSED_GET_EXTSIZE(dval) + VARHDRSZ;
 
        /* set external size and compression method */
        VARATT_EXTERNAL_SET_SIZE_AND_COMPRESS_METHOD(toast_pointer, data_todo,
                                                     VARDATA_COMPRESSED_GET_COMPRESS_METHOD(dval));
        /* Assert that the numbers look like it's compressed */
        Assert(VARATT_EXTERNAL_IS_COMPRESSED(toast_pointer));
    }
    else
    {
        data_p = VARDATA(dval);
        data_todo = VARSIZE(dval) - VARHDRSZ;
        toast_pointer.va_rawsize = VARSIZE(dval);
        toast_pointer.va_extinfo = data_todo;
    }
 
    /*
     * Insert the correct table OID into the result TOAST pointer.
     *
     * Normally this is the actual OID of the target toast table, but during
     * table-rewriting operations such as CLUSTER, we have to insert the OID
     * of the table's real permanent toast table instead.  rd_toastoid is set
     * if we have to substitute such an OID.
     */
    if (OidIsValid(rel->rd_toastoid))
        toast_pointer.va_toastrelid = rel->rd_toastoid;
    else
        toast_pointer.va_toastrelid = RelationGetRelid(toastrel);
 
    /*
     * Choose an OID to use as the value ID for this toast value.
     *
     * Normally we just choose an unused OID within the toast table.  But
     * during table-rewriting operations where we are preserving an existing
     * toast table OID, we want to preserve toast value OIDs too.  So, if
     * rd_toastoid is set and we had a prior external value from that same
     * toast table, re-use its value ID.  If we didn't have a prior external
     * value (which is a corner case, but possible if the table's attstorage
     * options have been changed), we have to pick a value ID that doesn't
     * conflict with either new or existing toast value OIDs.
     */
    if (!OidIsValid(rel->rd_toastoid))
    {
        /* normal case: just choose an unused OID */
        toast_pointer.va_valueid =
            GetNewOidWithIndex(toastrel,
                               RelationGetRelid(toastidxs[validIndex]),
                               (AttrNumber) 1);
    }
    else
    {
        /* rewrite case: check to see if value was in old toast table */
        toast_pointer.va_valueid = InvalidOid;
        if (oldexternal != NULL)
        {
            struct varatt_external old_toast_pointer;
 
            Assert(VARATT_IS_EXTERNAL_ONDISK(oldexternal));
            /* Must copy to access aligned fields */
            VARATT_EXTERNAL_GET_POINTER(old_toast_pointer, oldexternal);
            if (old_toast_pointer.va_toastrelid == rel->rd_toastoid)
            {
                /* This value came from the old toast table; reuse its OID */
                toast_pointer.va_valueid = old_toast_pointer.va_valueid;
 
                /*
                 * There is a corner case here: the table rewrite might have
                 * to copy both live and recently-dead versions of a row, and
                 * those versions could easily reference the same toast value.
                 * When we copy the second or later version of such a row,
                 * reusing the OID will mean we select an OID that's already
                 * in the new toast table.  Check for that, and if so, just
                 * fall through without writing the data again.
                 *
                 * While annoying and ugly-looking, this is a good thing
                 * because it ensures that we wind up with only one copy of
                 * the toast value when there is only one copy in the old
                 * toast table.  Before we detected this case, we'd have made
                 * multiple copies, wasting space; and what's worse, the
                 * copies belonging to already-deleted heap tuples would not
                 * be reclaimed by VACUUM.
                 */
                if (toastrel_valueid_exists(toastrel,
                                            toast_pointer.va_valueid))
                {
                    /* Match, so short-circuit the data storage loop below */
                    data_todo = 0;
                }
            }
        }
        if (toast_pointer.va_valueid == InvalidOid)
        {
            /*
             * new value; must choose an OID that doesn't conflict in either
             * old or new toast table
             */
            do
            {
                toast_pointer.va_valueid =
                    GetNewOidWithIndex(toastrel,
                                       RelationGetRelid(toastidxs[validIndex]),
                                       (AttrNumber) 1);
            } while (toastid_valueid_exists(rel->rd_toastoid,
                                            toast_pointer.va_valueid));
        }
    }
 
    /*
     * Initialize constant parts of the tuple data
     */
    t_values[0] = ObjectIdGetDatum(toast_pointer.va_valueid);
    t_values[2] = PointerGetDatum(&chunk_data);
    t_isnull[0] = false;
    t_isnull[1] = false;
    t_isnull[2] = false;
 
    /*
     * Split up the item into chunks
     */
    while (data_todo > 0)
    {
        int         i;
 
        CHECK_FOR_INTERRUPTS();
 
        /*
         * Calculate the size of this chunk
         */
        chunk_size = Min(TOAST_MAX_CHUNK_SIZE, data_todo);
 
        /*
         * Build a tuple and store it
         */
        t_values[1] = Int32GetDatum(chunk_seq++);
        SET_VARSIZE(&chunk_data, chunk_size + VARHDRSZ);
        memcpy(VARDATA(&chunk_data), data_p, chunk_size);
        toasttup = heap_form_tuple(toasttupDesc, t_values, t_isnull);
 
        heap_insert(toastrel, toasttup, mycid, options, NULL);
 
        /*
         * Create the index entry.  We cheat a little here by not using
         * FormIndexDatum: this relies on the knowledge that the index columns
         * are the same as the initial columns of the table for all the
         * indexes.  We also cheat by not providing an IndexInfo: this is okay
         * for now because btree doesn't need one, but we might have to be
         * more honest someday.
         *
         * Note also that there had better not be any user-created index on
         * the TOAST table, since we don't bother to update anything else.
         */
        for (i = 0; i < num_indexes; i++)
        {
            /* Only index relations marked as ready can be updated */
            if (toastidxs[i]->rd_index->indisready)
                index_insert(toastidxs[i], t_values, t_isnull,
                             &(toasttup->t_self),
                             toastrel,
                             toastidxs[i]->rd_index->indisunique ?
                             UNIQUE_CHECK_YES : UNIQUE_CHECK_NO,
                             false, NULL);
        }
 
        /*
         * Free memory
         */
        heap_freetuple(toasttup);
 
        /*
         * Move on to next chunk
         */
        data_todo -= chunk_size;
        data_p += chunk_size;
    }
 
    /*
     * Done - close toast relation and its indexes but keep the lock until
     * commit, so as a concurrent reindex done directly on the toast relation
     * would be able to wait for this transaction.
     */
    toast_close_indexes(toastidxs, num_indexes, NoLock);
    table_close(toastrel, NoLock);
 
    /*
     * Create the TOAST pointer value that we'll return
     */
    result = (struct varlena *) palloc(TOAST_POINTER_SIZE);
    SET_VARTAG_EXTERNAL(result, VARTAG_ONDISK);
    memcpy(VARDATA_EXTERNAL(result), &toast_pointer, sizeof(toast_pointer));
 
    return PointerGetDatum(result);
}

References Assert, CHECK_FOR_INTERRUPTS, data, DatumGetPointer(), GetCurrentCommandId(), GetNewOidWithIndex(), heap_form_tuple(), heap_freetuple(), heap_insert(), i, index_insert(), Int32GetDatum(), InvalidOid, Min, NoLock, ObjectIdGetDatum(), OidIsValid, palloc(), PointerGetDatum(), RelationData::rd_att, RelationData::rd_index, RelationData::rd_rel, RelationData::rd_toastoid, RelationGetRelid, RowExclusiveLock, SET_VARSIZE, SET_VARTAG_EXTERNAL, HeapTupleData::t_self, table_close(), table_open(), toast_close_indexes(), TOAST_MAX_CHUNK_SIZE, toast_open_indexes(), TOAST_POINTER_SIZE, toastid_valueid_exists(), toastrel_valueid_exists(), UNIQUE_CHECK_NO, UNIQUE_CHECK_YES, varatt_external::va_extinfo, varatt_external::va_rawsize, varatt_external::va_toastrelid, varatt_external::va_valueid, value, VARATT_EXTERNAL_GET_POINTER, VARATT_EXTERNAL_IS_COMPRESSED, VARATT_EXTERNAL_SET_SIZE_AND_COMPRESS_METHOD, VARATT_IS_COMPRESSED, VARATT_IS_EXTERNAL, VARATT_IS_EXTERNAL_ONDISK, VARATT_IS_SHORT, VARDATA, VARDATA_COMPRESSED_GET_COMPRESS_METHOD, VARDATA_COMPRESSED_GET_EXTSIZE, VARDATA_EXTERNAL, VARDATA_SHORT, VARHDRSZ, VARHDRSZ_SHORT, VARSIZE, VARSIZE_SHORT, and VARTAG_ONDISK.

Referenced by toast_tuple_externalize().