From 89eb18b7ca386aef6852e2f889987670f106454b Mon Sep 17 00:00:00 2001
From: Tomas Vondra <tomas@2ndquadrant.com>
Date: Tue, 15 Jan 2019 23:01:27 +0100
Subject: [PATCH 3/7] Change tmplinit argument tweaks

---
 src/include/tsearch/ts_cache.h  |  6 +--
 src/include/tsearch/ts_public.h | 87 ++++++++++++++++++---------------
 2 files changed, 51 insertions(+), 42 deletions(-)

diff --git a/src/include/tsearch/ts_cache.h b/src/include/tsearch/ts_cache.h
index cf3d870537..2298e0a275 100644
--- a/src/include/tsearch/ts_cache.h
+++ b/src/include/tsearch/ts_cache.h
@@ -54,9 +54,9 @@ typedef struct TSDictionaryCacheEntry
 	Oid			dictId;
 	bool		isvalid;
 
-	TransactionId dict_xmin;		/* XMIN of the dictionary's tuple */
-	TransactionId dict_xmax;		/* XMAX of the dictionary's tuple */
-	ItemPointerData dict_tid;		/* TID of the dictionary's tuple */
+	TransactionId	dict_xmin;	/* XMIN of the dictionary's tuple */
+	TransactionId	dict_xmax;	/* XMAX of the dictionary's tuple */
+	ItemPointerData	dict_tid;	/* TID of the dictionary's tuple */
 
 	/* most frequent fmgr call */
 	Oid			lexizeOid;
diff --git a/src/include/tsearch/ts_public.h b/src/include/tsearch/ts_public.h
index e169450de3..232cefc672 100644
--- a/src/include/tsearch/ts_public.h
+++ b/src/include/tsearch/ts_public.h
@@ -85,61 +85,71 @@ extern bool searchstoplist(StopList *s, char *key);
 /*
  * API for text search dictionaries.
  *
- * API functions to handle a text search dictionary are defined by a text search
- * template.  Currently an existing template cannot be altered in order to
- * define another functions.  API consists of the following functions:
- *	- init function - optional function which initializes internal structures of
- *	  the dictionary.  It accepts DictInitData structure as an argument and must
- *	  return a custom palloc'd structure which stores content of the processed
- *	  dictionary and is used in lexize function.
- *	- lexize function - normalizes a single word (token) using specific
- *	  dictionary.  It must return a palloc'd array of TSLexeme the last entry of
- *	  which is the terminating entry and accepts the following arguments:
- *	  - dictData - pointer to a custom structure returned by init function or
- *		NULL if init function wasn't defined by the template.
- *	  - token - string which represents a token to normalize, isn't
- *		null-terminated.
- *	  - length - length of token.
- *	  - dictState - pointer to a DictSubState structure which stores current
- *		state of a set of tokens processing and allows to normalize phrases.
+ * API functions to manage a text search dictionary are defined by a text search
+ * template.  Currently an existing template cannot be altered in order to use
+ * different functions.  API consists of the following functions:
+ *
+ * init function
+ * -------------
+ * - optional function which initializes internal structures of the dictionary
+ * - accepts DictInitData structure as an argument and must return a custom
+ *   palloc'd structure which stores content of the processed dictionary and
+ *   is used by lexize function
+ *
+ * lexize function
+ * ---------------
+ * - normalizes a single word (token) using specific dictionary
+ * - returns a palloc'd array of TSLexeme, with a terminating NULL entry
+ * - accepts the following arguments:
+ *
+ *	  - dictData - pointer to a structure returned by init function or NULL if
+ *	 	init function wasn't defined by the template
+ *	  - token - string to normalize (not null-terminated)
+ *	  - length - length of the token
+ *	  - dictState - pointer to a DictSubState structure storing current
+ *		state of a set of tokens processing and allows to normalize phrases
  */
 
 /*
- * A preprocessed dictionary can be stored in shared memory using DSM.  Does
- * the dictionary want it decides init function.  A DSM segment is released if
- * the dictionary was altered or droppped.  But still there is a situation when
- * we haven't a way to prevent a segment leaking.  It may happen if the
- * dictionary was dropped, some backend used the dictionary before dropping, the
- * backend will hold its DSM segment till disconnecting or calling
- * lookup_ts_dictionary_cache(), where invalid segment is unpinned.
+ * A preprocessed dictionary can be stored in shared memory using DSM - this is
+ * decided in the init function.  A DSM segment is released after altering or
+ * dropping the dictionary.  The segment may still leak, when a backend uses the
+ * dictionary right before dropping - in that case the backend will hold the DSM
+ * untill it disconnects or calls lookup_ts_dictionary_cache().
  *
- * DictPointerData is a structure to search a dictionary's DSM segment.  We
- * need xmin, xmax and tid to be sure that the content in the DSM segment still
- * valid.
+ * DictPointerData represents DSM segment with a preprocessed dictionary.  We
+ * need to ensure the content of the DSM segment is still valid, which is what
+ * xmin, xmax and tid are for.
  */
 typedef struct
 {
-	Oid			id;				/* OID of dictionary which is processed */
-	TransactionId xmin;			/* XMIN of the dictionary's tuple */
-	TransactionId xmax;			/* XMAX of the dictionary's tuple */
-	ItemPointerData tid;		/* TID of the dictionary's tuple */
+	Oid				id;			/* OID of the dictionary */
+	TransactionId	xmin;		/* XMIN of the dictionary's tuple */
+	TransactionId	xmax;		/* XMAX of the dictionary's tuple */
+	ItemPointerData	tid;		/* TID of the dictionary's tuple */
 } DictPointerData;
 
 /*
  * API structure for a dictionary initialization.  It is passed as an argument
  * to a template's init function.
+ *
+ * XXX Why do we even do it this way, instead of simply passing two parameters
+ * to the tmplinit function?
  */
 typedef struct
 {
 	/*
-	 * A dictionary option list for a template's init method. Should go first
-	 * for backward compatibility.
+	 * List of options for a template's init method (should go first for
+	 * backwards compatibility).
+	 *
+	 * XXX The backwards compatibility argument seems a bit bogus, because this
+	 * struct did not exist before anyway, and the functions were accepting List
+	 * instead. So the extensions will have to be updated anyway, to prevent
+	 * warnings about incorrect signatures / types.
 	 */
 	List	   *dict_options;
-	/*
-	 * A dictionary information used to allocate, search and release its DSM
-	 * segment.
-	 */
+
+	/* pointer used to allocate, search and release the DSM segment */
 	DictPointerData dict;
 } DictInitData;
 
@@ -170,8 +180,7 @@ typedef struct
 
 	uint16		flags;			/* See flag bits below */
 
-	char	   *lexeme;			/* C string or NULL if it is a terminating
-								 * entry */
+	char	   *lexeme;			/* C string (NULL for terminating entry) */
 } TSLexeme;
 
 /* Flag bits that can appear in TSLexeme.flags */
-- 
2.17.2

