#pragma once

#include <string_view>

/**
 * @file SymbolEvent.hpp
 * @brief hot_reload::SymbolEvent -- what happened to one symbol during a Context::reload() call.
 *
 * Carries the same meaning as hot_reload.h's `HotReloadSymbolEvent`; see Status.hpp's file
 * comment for how the C and C++ APIs relate.
 */
namespace hot_reload
{

	/**
	 * @brief One symbol's outcome during a Context::reload() call, reported through
	 *        Options::onSymbolEvent.
	 *
	 * Reload diffs the previous build's exported functions against the new build's by name;
	 * every name on either side gets exactly one of these.
	 */
	enum class SymbolEvent
	{
		/**
		 * Present, and a function, in both builds, with a different compiled body -- and
		 * successfully redirected: every existing caller of the old address, including one
		 * that cached the pointer directly, now runs the new build's code.
		 */
		Patched,

		/** A function in the new build with no same-named symbol in the previous one at all. */
		Added,

		/**
		 * In the previous build, not in the new one. The default: the old implementation keeps
		 * running as-is unless Options::onDeletedSymbol supplies a stub for it.
		 */
		Removed,

		/**
		 * Present in both builds, but not classified as a function (ELF `STT_FUNC` in an
		 * executable section, or a PE export whose address falls inside one) on at least one
		 * side -- the mechanical half of this library's "only executable code is ever touched"
		 * guarantee. Most often an exported variable; never patched, in either direction.
		 */
		SkippedNotCode,

		/**
		 * Present, and a function, in both builds -- but the previous build's compiled body
		 * was not large enough to safely hold the jump this library writes over a function's
		 * entry. Skipped rather than guessed. Compile the module with
		 * `-fpatchable-function-entry=32,0` (GCC/Clang) or `/hotpatch` (MSVC) to stop this from
		 * happening; `hot_reload_enable_patchable_functions()` in `cmake/HotReload.cmake`
		 * applies whichever one your compiler needs.
		 */
		SkippedTooSmall,

		/**
		 * Present, and a function, and large enough -- but the operating system refused to make
		 * that page of memory temporarily writable (an unusually locked-down environment).
		 */
		SkippedUnwritable,
	};

	/**
	 * @brief A short, human-readable label for @p event, suitable for logging.
	 * @param event The event to describe.
	 * @return A `string_view` into a static string -- valid for the life of the program.
	 */
	[[nodiscard]] std::string_view toString(SymbolEvent event) noexcept;

}