/*-------------------------------------------------------------------------

 *

 * toast_helper.c

 *    Helper functions for table AMs implementing compressed or

 *    out-of-line storage of varlena attributes.

 *

 * Copyright (c) 2000-2026, PostgreSQL Global Development Group

 *

 * IDENTIFICATION

 *    src/backend/access/table/toast_helper.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include "access/detoast.h"

#include "access/toast_helper.h"

#include "access/toast_internals.h"

#include "catalog/pg_type_d.h"

#include "varatt.h"

/*

 * Prepare to TOAST a tuple.

 *

 * tupleDesc, toast_values, and toast_isnull are required parameters; they

 * provide the necessary details about the tuple to be toasted.

 *

 * toast_oldvalues and toast_oldisnull should be NULL for a newly-inserted

 * tuple; for an update, they should describe the existing tuple.

 *

 * All of these arrays should have a length equal to tupleDesc->natts.

 *

 * On return, toast_flags and toast_attr will have been initialized.

 * toast_flags is just a single uint8, but toast_attr is a caller-provided

 * array with a length equal to tupleDesc->natts.  The caller need not

 * perform any initialization of the array before calling this function.

 */

void

toast_tuple_init(ToastTupleContext *ttc)

{

  TupleDesc tupleDesc = ttc->ttc_rel->rd_att;

  int     numAttrs = tupleDesc->natts;

  int     i;

  ttc->ttc_flags = 0;

  for (i = 0; i < numAttrs; i++)

  {

    Form_pg_attribute att = TupleDescAttr(tupleDesc, i);

    varlena    *old_value;

    varlena    *new_value;

    ttc->ttc_attr[i].tai_colflags = 0;

    ttc->ttc_attr[i].tai_oldexternal = NULL;

    ttc->ttc_attr[i].tai_compression = att->attcompression;

    if (ttc->ttc_oldvalues != NULL)

    {

      /*

       * For UPDATE get the old and new values of this attribute

       */

      old_value =

        (varlena *) DatumGetPointer(ttc->ttc_oldvalues[i]);

      new_value =

        (varlena *) DatumGetPointer(ttc->ttc_values[i]);

      /*

       * If the old value is stored on disk, check if it has changed so

       * we have to delete it later.

       *

       * Note that TOAST pointers could have different vartags, for oid

       * or oid8, and these can have different sizes.

       */

      if (att->attlen == -1 && !ttc->ttc_oldisnull[i] &&

        VARATT_IS_EXTERNAL_ONDISK(old_value))

      {

        if (ttc->ttc_isnull[i] ||

          !VARATT_IS_EXTERNAL_ONDISK(new_value) ||

          VARTAG_EXTERNAL(old_value) != VARTAG_EXTERNAL(new_value) ||

          memcmp(old_value, new_value,

               VARSIZE_EXTERNAL(old_value)) != 0)

        {

          /*

           * The old external stored value isn't needed any more

           * after the update

           */

          ttc->ttc_attr[i].tai_colflags |= TOASTCOL_NEEDS_DELETE_OLD;

          ttc->ttc_flags |= TOAST_NEEDS_DELETE_OLD;

        }

        else

        {

          /*

           * This attribute isn't changed by this update so we reuse

           * the original reference to the old value in the new

           * tuple.

           */

          ttc->ttc_attr[i].tai_colflags |= TOASTCOL_IGNORE;

          continue;

        }

      }

    }

    else

    {

      /*

       * For INSERT simply get the new value

       */

      new_value = (varlena *) DatumGetPointer(ttc->ttc_values[i]);

    }

    /*

     * Handle NULL attributes

     */

    if (ttc->ttc_isnull[i])

    {

      ttc->ttc_attr[i].tai_colflags |= TOASTCOL_IGNORE;

      ttc->ttc_flags |= TOAST_HAS_NULLS;

      continue;

    }

    /*

     * Now look at varlena attributes

     */

    if (att->attlen == -1)

    {

      /*

       * If the table's attribute says PLAIN always, force it so.

       */

      if (att->attstorage == TYPSTORAGE_PLAIN)

        ttc->ttc_attr[i].tai_colflags |= TOASTCOL_IGNORE;

      /*

       * We took care of UPDATE above, so any external value we find

       * still in the tuple must be someone else's that we cannot reuse

       * (this includes the case of an out-of-line in-memory datum).

       * Fetch it back (without decompression, unless we are forcing

       * PLAIN storage).  If necessary, we'll push it out as a new

       * external value below.

       */

      if (VARATT_IS_EXTERNAL(new_value))

      {

        ttc->ttc_attr[i].tai_oldexternal = new_value;

        if (att->attstorage == TYPSTORAGE_PLAIN)

          new_value = detoast_attr(new_value);

        else

          new_value = detoast_external_attr(new_value);

        ttc->ttc_values[i] = PointerGetDatum(new_value);

        ttc->ttc_attr[i].tai_colflags |= TOASTCOL_NEEDS_FREE;

        ttc->ttc_flags |= (TOAST_NEEDS_CHANGE | TOAST_NEEDS_FREE);

      }

      /*

       * Remember the size of this attribute

       */

      ttc->ttc_attr[i].tai_size = VARSIZE_ANY(new_value);

    }

    else

    {

      /*

       * Not a varlena attribute, plain storage always

       */

      ttc->ttc_attr[i].tai_colflags |= TOASTCOL_IGNORE;

    }

  }

}

/*

 * Find the largest varlena attribute that satisfies certain criteria.

 *

 * The relevant column must not be marked TOASTCOL_IGNORE, and if the

 * for_compression flag is passed as true, it must also not be marked

 * TOASTCOL_INCOMPRESSIBLE.

 *

 * The column must have attstorage EXTERNAL or EXTENDED if check_main is

 * false, and must have attstorage MAIN if check_main is true.

 *

 * The column must be larger than the TOAST pointer that would replace it;

 * if not, no benefit is to be expected by compressing it.  Note that this

 * choice depends on the TOAST value type, oid or oid8.

 *

 * The return value is the index of the biggest suitable column, or

 * -1 if there is none.

 */

int

toast_tuple_find_biggest_attribute(ToastTupleContext *ttc,

                   bool for_compression, bool check_main)

{

  TupleDesc tupleDesc = ttc->ttc_rel->rd_att;

  int     numAttrs = tupleDesc->natts;

  int     biggest_attno = -1;

  int32   biggest_size;

  int32   skip_colflags = TOASTCOL_IGNORE;

  int     i;

  /*

   * Size of the TOAST pointer this relation would use.  A relation without

   * a TOAST table cannot have any of its attributes moved out-of-line, but

   * it can still have some of them compressed.  Fall back to the oid size

   * in that case.

   */

  if (RelationGetToastChunkIdType(ttc->ttc_rel) == OID8OID)

    biggest_size = MAXALIGN(TOAST_OID8_POINTER_SIZE);

  else

    biggest_size = MAXALIGN(TOAST_OID_POINTER_SIZE);

  if (for_compression)

    skip_colflags |= TOASTCOL_INCOMPRESSIBLE;

  for (i = 0; i < numAttrs; i++)

  {

    Form_pg_attribute att = TupleDescAttr(tupleDesc, i);

    if ((ttc->ttc_attr[i].tai_colflags & skip_colflags) != 0)

      continue;

    if (VARATT_IS_EXTERNAL(DatumGetPointer(ttc->ttc_values[i])))

      continue;     /* can't happen, toast_action would be PLAIN */

    if (for_compression &&

      VARATT_IS_COMPRESSED(DatumGetPointer(ttc->ttc_values[i])))

      continue;

    if (check_main && att->attstorage != TYPSTORAGE_MAIN)

      continue;

    if (!check_main && att->attstorage != TYPSTORAGE_EXTENDED &&

      att->attstorage != TYPSTORAGE_EXTERNAL)

      continue;

    if (ttc->ttc_attr[i].tai_size > biggest_size)

    {

      biggest_attno = i;

      biggest_size = ttc->ttc_attr[i].tai_size;

    }

  }

  return biggest_attno;

}

/*

 * Try compression for an attribute.

 *

 * If we find that the attribute is not compressible, mark it so.

 */

void

toast_tuple_try_compression(ToastTupleContext *ttc, int attribute)

{

  Datum    *value = &ttc->ttc_values[attribute];

  Datum   new_value;

  ToastAttrInfo *attr = &ttc->ttc_attr[attribute];

  new_value = toast_compress_datum(*value, attr->tai_compression);

  if (DatumGetPointer(new_value) != NULL)

  {

    /* successful compression */

    if ((attr->tai_colflags & TOASTCOL_NEEDS_FREE) != 0)

      pfree(DatumGetPointer(*value));

    *value = new_value;

    attr->tai_colflags |= TOASTCOL_NEEDS_FREE;

    attr->tai_size = VARSIZE(DatumGetPointer(*value));

    ttc->ttc_flags |= (TOAST_NEEDS_CHANGE | TOAST_NEEDS_FREE);

  }

  else

  {

    /* incompressible, ignore on subsequent compression passes */

    attr->tai_colflags |= TOASTCOL_INCOMPRESSIBLE;

  }

}

/*

 * Move an attribute to external storage.

 */

void

toast_tuple_externalize(ToastTupleContext *ttc, int attribute, uint32 options)

{

  Datum    *value = &ttc->ttc_values[attribute];

  Datum   old_value = *value;

  ToastAttrInfo *attr = &ttc->ttc_attr[attribute];

  attr->tai_colflags |= TOASTCOL_IGNORE;

  *value = toast_save_datum(ttc->ttc_rel, old_value, attr->tai_oldexternal,

                options);

  if ((attr->tai_colflags & TOASTCOL_NEEDS_FREE) != 0)

    pfree(DatumGetPointer(old_value));

  attr->tai_colflags |= TOASTCOL_NEEDS_FREE;

  ttc->ttc_flags |= (TOAST_NEEDS_CHANGE | TOAST_NEEDS_FREE);

}

/*

 * Perform appropriate cleanup after one tuple has been subjected to TOAST.

 */

void

toast_tuple_cleanup(ToastTupleContext *ttc)

{

  TupleDesc tupleDesc = ttc->ttc_rel->rd_att;

  int     numAttrs = tupleDesc->natts;

  /*

   * Free allocated temp values

   */

  if ((ttc->ttc_flags & TOAST_NEEDS_FREE) != 0)

  {

    int     i;

    for (i = 0; i < numAttrs; i++)

    {

      ToastAttrInfo *attr = &ttc->ttc_attr[i];

      if ((attr->tai_colflags & TOASTCOL_NEEDS_FREE) != 0)

        pfree(DatumGetPointer(ttc->ttc_values[i]));

    }

  }

  /*

   * Delete external values from the old tuple

   */

  if ((ttc->ttc_flags & TOAST_NEEDS_DELETE_OLD) != 0)

  {

    int     i;

    for (i = 0; i < numAttrs; i++)

    {

      ToastAttrInfo *attr = &ttc->ttc_attr[i];

      if ((attr->tai_colflags & TOASTCOL_NEEDS_DELETE_OLD) != 0)

        toast_delete_datum(ttc->ttc_rel, ttc->ttc_oldvalues[i], false);

    }

  }

}

/*

 * Check for external stored attributes and delete them from the secondary

 * relation.

 */

void

toast_delete_external(Relation rel, const Datum *values, const bool *isnull,

            bool is_speculative)

{

  TupleDesc tupleDesc = rel->rd_att;

  int     numAttrs = tupleDesc->natts;

  int     i;

  for (i = 0; i < numAttrs; i++)

  {

    if (TupleDescCompactAttr(tupleDesc, i)->attlen == -1)

    {

      Datum   value = values[i];

      if (isnull[i])

        continue;

      else if (VARATT_IS_EXTERNAL_ONDISK(DatumGetPointer(value)))

        toast_delete_datum(rel, value, is_speculative);

    }

  }

}