From 89eb18b7ca386aef6852e2f889987670f106454b Mon Sep 17 00:00:00 2001 From: Tomas Vondra 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