/*
 * multixact_read_v18.c
 *
 * Functions to read multixact SLRUs from clusters of PostgreSQL version 18
 * and older.  In version 19, the multixid offsets were expanded from 32 to 64
 * bits.
 *
 * Copyright (c) 2025-2026, PostgreSQL Global Development Group
 * src/bin/pg_upgrade/multixact_read_v18.c
 */

#include "postgres_fe.h"

#include "multixact_read_v18.h"
#include "pg_upgrade.h"

/*
 * NOTE: below are a bunch of definitions that are copy-pasted from
 * multixact.c from version 18.  It's important that this file doesn't
 * #include the new definitions with same names from "multixact_internal.h"!
 *
 * To further avoid confusion in the functions exposed outside this source
 * file, we use MultiXactOffset32 to represent the old-style 32-bit multixid
 * offsets.  The new 64-bit MultiXactOffset should not be used anywhere in
 * this file.
 */
#ifdef MULTIXACT_INTERNAL_H
#error multixact_internal.h should not be included in multixact_read_v18.c
#endif
#define MultiXactOffset should_not_be_used

/* We need four bytes per offset and 8 bytes per base for each page. */
#define MULTIXACT_OFFSETS_PER_PAGE (BLCKSZ / sizeof(MultiXactOffset32))

static inline int64
MultiXactIdToOffsetPage(MultiXactId multi)
{
	return multi / MULTIXACT_OFFSETS_PER_PAGE;
}

static inline int
MultiXactIdToOffsetEntry(MultiXactId multi)
{
	return multi % MULTIXACT_OFFSETS_PER_PAGE;
}

/*
 * The situation for members is a bit more complex: we store one byte of
 * additional flag bits for each TransactionId.  To do this without getting
 * into alignment issues, we store four bytes of flags, and then the
 * corresponding 4 Xids.  Each such 5-word (20-byte) set we call a "group", and
 * are stored as a whole in pages.  Thus, with 8kB BLCKSZ, we keep 409 groups
 * per page.  This wastes 12 bytes per page, but that's OK -- simplicity (and
 * performance) trumps space efficiency here.
 *
 * Note that the "offset" macros work with byte offset, not array indexes, so
 * arithmetic must be done using "char *" pointers.
 */
/* We need eight bits per xact, so one xact fits in a byte */
#define MXACT_MEMBER_BITS_PER_XACT			8
#define MXACT_MEMBER_FLAGS_PER_BYTE			1
#define MXACT_MEMBER_XACT_BITMASK	((1 << MXACT_MEMBER_BITS_PER_XACT) - 1)

/* how many full bytes of flags are there in a group? */
#define MULTIXACT_FLAGBYTES_PER_GROUP		4
#define MULTIXACT_MEMBERS_PER_MEMBERGROUP	\
	(MULTIXACT_FLAGBYTES_PER_GROUP * MXACT_MEMBER_FLAGS_PER_BYTE)
/* size in bytes of a complete group */
#define MULTIXACT_MEMBERGROUP_SIZE \
	(sizeof(TransactionId) * MULTIXACT_MEMBERS_PER_MEMBERGROUP + MULTIXACT_FLAGBYTES_PER_GROUP)
#define MULTIXACT_MEMBERGROUPS_PER_PAGE (BLCKSZ / MULTIXACT_MEMBERGROUP_SIZE)
#define MULTIXACT_MEMBERS_PER_PAGE	\
	(MULTIXACT_MEMBERGROUPS_PER_PAGE * MULTIXACT_MEMBERS_PER_MEMBERGROUP)

/* page in which a member is to be found */
static inline int64
MXOffsetToMemberPage(MultiXactOffset32 offset)
{
	return offset / MULTIXACT_MEMBERS_PER_PAGE;
}

/* Location (byte offset within page) of flag word for a given member */
static inline int
MXOffsetToFlagsOffset(MultiXactOffset32 offset)
{
	MultiXactOffset32 group = offset / MULTIXACT_MEMBERS_PER_MEMBERGROUP;
	int			grouponpg = group % MULTIXACT_MEMBERGROUPS_PER_PAGE;
	int			byteoff = grouponpg * MULTIXACT_MEMBERGROUP_SIZE;

	return byteoff;
}

/* Location (byte offset within page) of TransactionId of given member */
static inline int
MXOffsetToMemberOffset(MultiXactOffset32 offset)
{
	int			member_in_group = offset % MULTIXACT_MEMBERS_PER_MEMBERGROUP;

	return MXOffsetToFlagsOffset(offset) +
		MULTIXACT_FLAGBYTES_PER_GROUP +
		member_in_group * sizeof(TransactionId);
}

static inline int
MXOffsetToFlagsBitShift(MultiXactOffset32 offset)
{
	int			member_in_group = offset % MULTIXACT_MEMBERS_PER_MEMBERGROUP;
	int			bshift = member_in_group * MXACT_MEMBER_BITS_PER_XACT;

	return bshift;
}

/*
 * Construct reader of old multixacts.
 *
 * Returns the malloced memory used by the all other calls in this module.
 */
OldMultiXactReader *
AllocOldMultiXactRead(char *pgdata, MultiXactId nextMulti,
					  MultiXactOffset32 nextOffset)
{
	OldMultiXactReader *state = pg_malloc_object(OldMultiXactReader);
	char		dir[MAXPGPATH] = {0};

	state->nextMXact = nextMulti;
	state->nextOffset = nextOffset;

	pg_sprintf(dir, "%s/pg_multixact/offsets", pgdata);
	state->offset = AllocSlruRead(dir, false);

	pg_sprintf(dir, "%s/pg_multixact/members", pgdata);
	state->members = AllocSlruRead(dir, false);

	return state;
}

/*
 * This is a simplified version of the GetMultiXactIdMembers() server
 * function:
 *
 * - Only return the updating member, if any.  Upgrade only cares about the
 *   updaters.  If there is no updating member, return somewhat arbitrarily
 *   the first locking-only member, because we don't have any way to represent
 *   "no members".
 *
 * - Because there's no concurrent activity, we don't need to worry about
 *   locking and some corner cases.
 *
 * - Don't bail out on invalid entries that could've been left behind after a
 *   server crash.  Such multixids won't appear anywhere else on disk, so the
 *   server will never try to read them.  During upgrade, however, we scan
 *   through all multixids in order, and will encounter such invalid but
 *   unreferenced multixids too.  We try to distinguish between entries that
 *   are invalid because of missed disk writes, like entries with zeros in
 *   offsets or members, and entries that look corrupt in other ways that
 *   should not happen even on a server crash.
 *
 * Returns true on success, false if the multixact was invalid.
 */
bool
GetOldMultiXactIdSingleMember(OldMultiXactReader *state, MultiXactId multi,
							  MultiXactMember *member)
{
	MultiXactId nextMXact,
				nextOffset,
				tmpMXact;
	int64		pageno,
				prev_pageno;
	int			entryno,
				length;
	char	   *buf;
	MultiXactOffset32 *offptr,
				offset;
	MultiXactOffset32 nextMXOffset;
	TransactionId result_xid = InvalidTransactionId;
	MultiXactStatus result_status = 0;

	nextMXact = state->nextMXact;
	nextOffset = state->nextOffset;

	/*
	 * Comment copied from GetMultiXactIdMembers in PostgreSQL v18
	 * multixact.c:
	 *
	 * Find out the offset at which we need to start reading MultiXactMembers
	 * and the number of members in the multixact.  We determine the latter as
	 * the difference between this multixact's starting offset and the next
	 * one's.  However, there are some corner cases to worry about:
	 *
	 * 1. This multixact may be the latest one created, in which case there is
	 * no next one to look at.  The next multixact's offset should be set
	 * already, as we set it in RecordNewMultiXact(), but we used to not do
	 * that in older minor versions.  To cope with that case, if this
	 * multixact is the latest one created, use the nextOffset value we read
	 * above as the endpoint.
	 *
	 * 2. Because GetNewMultiXactId skips over offset zero, to reserve zero
	 * for to mean "unset", there is an ambiguity near the point of offset
	 * wraparound.  If we see next multixact's offset is one, is that our
	 * multixact's actual endpoint, or did it end at zero with a subsequent
	 * increment?  We handle this using the knowledge that if the zero'th
	 * member slot wasn't filled, it'll contain zero, and zero isn't a valid
	 * transaction ID so it can't be a multixact member.  Therefore, if we
	 * read a zero from the members array, just ignore it.
	 */

	pageno = MultiXactIdToOffsetPage(multi);
	entryno = MultiXactIdToOffsetEntry(multi);

	buf = SlruReadSwitchPage(state->offset, pageno);
	offptr = (MultiXactOffset32 *) buf;
	offptr += entryno;
	offset = *offptr;

	if (offset == 0)
	{
		/* Invalid entry.  These can be left behind on a server crash. */
		return false;
	}

	/*
	 * Use the same increment rule as GetNewMultiXactId(), that is, don't
	 * handle wraparound explicitly until needed.
	 */
	tmpMXact = multi + 1;

	if (nextMXact == tmpMXact)
	{
		/* Corner case 1: there is no next multixact */
		nextMXOffset = nextOffset;
	}
	else
	{
		/* handle wraparound if needed */
		if (tmpMXact < FirstMultiXactId)
			tmpMXact = FirstMultiXactId;

		prev_pageno = pageno;

		pageno = MultiXactIdToOffsetPage(tmpMXact);
		entryno = MultiXactIdToOffsetEntry(tmpMXact);

		if (pageno != prev_pageno)
			buf = SlruReadSwitchPage(state->offset, pageno);

		offptr = (MultiXactOffset32 *) buf;
		offptr += entryno;
		nextMXOffset = *offptr;
	}

	if (nextMXOffset == 0)
	{
		/* Invalid entry.  These can be left behind on a server crash. */
		return false;
	}
	length = nextMXOffset - offset;

	if (length < 0)
	{
		/*
		 * This entry is corrupt.  We should not see these even after a server
		 * crash.
		 */
		pg_fatal("multixact %u has an invalid length (%d)", multi, length);
	}
	if (length == 0)
	{
		/*
		 * Invalid entry.  The server never writes multixids with zero
		 * members, but it's not clear if a server crash or using pg_resetwal
		 * could leave them behind.  Seems best to accept them.
		 */
		return false;
	}

	/* read the members */
	prev_pageno = -1;
	for (int i = 0; i < length; i++, offset++)
	{
		TransactionId *xactptr;
		uint32	   *flagsptr;
		int			flagsoff;
		int			bshift;
		int			memberoff;
		MultiXactStatus status;

		pageno = MXOffsetToMemberPage(offset);
		memberoff = MXOffsetToMemberOffset(offset);

		if (pageno != prev_pageno)
		{
			buf = SlruReadSwitchPage(state->members, pageno);
			prev_pageno = pageno;
		}

		xactptr = (TransactionId *) (buf + memberoff);
		if (!TransactionIdIsValid(*xactptr))
		{
			/*
			 * Corner case 2: offset must have wrapped around to unused slot
			 * zero.
			 */
			if (offset == 0)
				continue;

			/*
			 * Otherwise this is an invalid entry that should not be
			 * referenced from anywhere in the heap.  These can be left behind
			 * on a server crash.  We could return 'false' here, but we prefer
			 * to continue reading the members and converting them the best we
			 * can, to preserve evidence in case this is corruption that
			 * should not have happened.
			 */
		}

		flagsoff = MXOffsetToFlagsOffset(offset);
		bshift = MXOffsetToFlagsBitShift(offset);
		flagsptr = (uint32 *) (buf + flagsoff);

		status = (*flagsptr >> bshift) & MXACT_MEMBER_XACT_BITMASK;

		/*
		 * Remember the updating XID among the members, or first locking XID
		 * if no updating XID.
		 */
		if (ISUPDATE_from_mxstatus(status))
		{
			/* sanity check */
			if (ISUPDATE_from_mxstatus(result_status))
			{
				/*
				 * We don't expect to see more than one updating member, even
				 * if the server had crashed.
				 */
				pg_fatal("multixact %u has more than one updating member",
						 multi);
			}
			result_xid = *xactptr;
			result_status = status;
		}
		else if (!TransactionIdIsValid(result_xid))
		{
			result_xid = *xactptr;
			result_status = status;
		}
	}

	member->xid = result_xid;
	member->status = result_status;
	return true;
}

/*
 * Frees the malloced reader.
 */
void
FreeOldMultiXactReader(OldMultiXactReader *state)
{
	FreeSlruRead(state->offset);
	FreeSlruRead(state->members);

	pfree(state);
}