/*-------------------------------------------------------------------------
 *
 * funccache.h
 *   Function cache definitions.
 *
 * See funccache.c for comments.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/funccache.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef FUNCCACHE_H
#define FUNCCACHE_H

#include "access/htup_details.h"
#include "fmgr.h"
#include "storage/itemptr.h"

struct CachedFunctionHashKey; /* forward references */
struct CachedFunction;

/*
 * Callback that cached_function_compile() invokes when it's necessary to
 * compile a cached function.  The callback must fill in *function (except
 * for the fields of struct CachedFunction), or throw an error if trouble.
 * fcinfo: current call information
 * procTup: function's pg_proc row from catcache
 * hashkey: hash key that will be used for the function
 * function: pre-zeroed workspace, of size passed to cached_function_compile()
 * forValidator: passed through from cached_function_compile()
 */
typedef void (*CachedFunctionCompileCallback) (FunctionCallInfo fcinfo,
              HeapTuple procTup,
              const struct CachedFunctionHashKey *hashkey,
              struct CachedFunction *function,
              bool forValidator);

/*
 * Callback called when discarding a cache entry.  Free any free-able
 * subsidiary data of cfunc, but not the struct CachedFunction itself.
 */
typedef void (*CachedFunctionDeleteCallback) (struct CachedFunction *cfunc);

/*
 * Hash lookup key for functions.  This must account for all aspects
 * of a specific call that might lead to different data types or
 * collations being used within the function.
 */
typedef struct CachedFunctionHashKey
{
 Oid   funcOid;

 bool  isTrigger;  /* true if called as a DML trigger */
 bool  isEventTrigger; /* true if called as an event trigger */

 /* be careful that pad bytes in this struct get zeroed! */

 /*
  * We include the language-specific size of the function's cache entry in
  * the cache key.  This covers the case where CREATE OR REPLACE FUNCTION
  * is used to change the implementation language, and the new language
  * also uses funccache.c but needs a different-sized cache entry.
 */
 Size  cacheEntrySize;

 /*
  * For a trigger function, the OID of the trigger is part of the hash key
  * --- we want to compile the trigger function separately for each trigger
  * it is used with, in case the rowtype or transition table names are
  * different.  Zero if not called as a DML trigger.
 */
 Oid   trigOid;

 /*
  * We must include the input collation as part of the hash key too,
  * because we have to generate different plans (with different Param
  * collations) for different collation settings.
 */
 Oid   inputCollation;

 /* Number of arguments (counting input arguments only, ie pronargs) */
 int   nargs;

 /* If you change anything below here, fix hashing code in funccache.c! */

 /*
  * If relevant, the result descriptor for a function returning composite.
 */
 TupleDesc callResultType;

 /*
  * Input argument types, with any polymorphic types resolved to actual
  * types.  Only the first nargs entries are valid.
 */
 Oid   argtypes[FUNC_MAX_ARGS];
} CachedFunctionHashKey;

/*
 * Representation of a compiled function.  This struct contains just the
 * fields that funccache.c needs to deal with.  It will typically be
 * embedded in a larger struct containing function-language-specific data.
 */
typedef struct CachedFunction
{
 /* back-link to hashtable entry, or NULL if not in hash table */
 CachedFunctionHashKey *fn_hashkey;
 /* xmin and ctid of function's pg_proc row; used to detect invalidation */
 TransactionId fn_xmin;
 ItemPointerData fn_tid;
 /* deletion callback */
 CachedFunctionDeleteCallback dcallback;

 /* this field changes when the function is used: */
 uint64  use_count;
} CachedFunction;

extern CachedFunction *cached_function_compile(FunctionCallInfo fcinfo,
              CachedFunction *function,
              CachedFunctionCompileCallback ccallback,
              CachedFunctionDeleteCallback dcallback,
              Size cacheEntrySize,
              bool includeResultType,
              bool forValidator);
extern void cfunc_resolve_polymorphic_argtypes(int numargs,
              Oid *argtypes,
              char *argmodes,
              Node *call_expr,
              bool forValidator,
              const char *proname);

#endif       /* FUNCCACHE_H */