naoa
null+****@clear*****
Sat Jun 21 10:46:38 JST 2014
naoa 2014-06-21 10:46:38 +0900 (Sat, 21 Jun 2014) New Revision: ac9228c21a9033e3308730cca46caf79413a9440 https://github.com/groonga/groonga/commit/ac9228c21a9033e3308730cca46caf79413a9440 Merged 93234ed: Merge pull request #179 from naoa/doc-move-plugin-api-reference Message: doc:move plugin API documents from plugin.h to Sphinx text TODO: More describe it in doc/source/reference/api/plugin.rst Translate it in doc/locale/ja/LC_MESSAGES/reference.po Translate it in doc/locale/en/LC_MESSAGES/reference.po Modified files: doc/source/reference/api/plugin.rst include/groonga/plugin.h Modified: doc/source/reference/api/plugin.rst (+92 -1) =================================================================== --- doc/source/reference/api/plugin.rst 2014-06-20 23:54:27 +0900 (3c8ec99) +++ doc/source/reference/api/plugin.rst 2014-06-21 10:46:38 +0900 (8b74a63) @@ -17,6 +17,76 @@ tutorial about it. Reference --------- +.. c:function:: grn_rc GRN_PLUGIN_INIT(grn_ctx *ctx) + +.. c:function:: grn_rc GRN_PLUGIN_REGISTER(grn_ctx *ctx) + +.. c:function:: grn_rc GRN_PLUGIN_FIN(grn_ctx *ctx) + +.. c:macro:: GRN_PLUGIN_MALLOC(ctx, size) + + GRN_PLUGIN_MALLOC() allocates `size` bytes and returns a pointer to the + allocated memory space. Note that the memory space is associated with `ctx`. + +.. c:macro:: GRN_PLUGIN_REALLOC(ctx, ptr, size) + + GRN_PLUGIN_REALLOC() resizes the memory space pointed to by `ptr` or + allocates a new memory space of `size` bytes. GRN_PLUGIN_REALLOC() returns + a pointer to the memory space. The contents is unchanged or copied from the + old memory space to the new memory space. + +.. c:macro:: GRN_PLUGIN_FREE(ctx, ptr) + + GRN_PLUGIN_FREE() frees a memory space allocated by GRN_PLUGIN_MALLOC() or + GRN_PLUGIN_REALLOC(). This means that `ptr` must be a pointer returned by + GRN_PLUGIN_MALLOC() or GRN_PLUGIN_REALLOC(). + +.. c:macro:: GRN_PLUGIN_LOG(ctx, level, ...) + + GRN_PLUGIN_LOG() reports a log of `level`. Its error message is generated + from the varying number of arguments, in which the first one is the format + string and the rest are its arguments. See grn_log_level in "groonga.h" for + more details of `level`. + +.. c:macro:: GRN_PLUGIN_ERROR(ctx, error_code, ...) + + GRN_PLUGIN_ERROR() reports an error of `error_code`. Its error message is + generated from the varying number of arguments, in which the first one is the + format string and the rest are its arguments. See grn_rc in "groonga.h" for + more details of `error_code`. + +.. c:type:: grn_plugin_mutex + + grn_plugin_mutex is available to make a critical section. See the + following functions. + +.. c:function:: grn_plugin_mutex *grn_plugin_mutex_open(grn_ctx *ctx) + + grn_plugin_mutex_open() returns a pointer to a new object of + grn_plugin_mutex. Memory for the new object is obtained with + GRN_PLUGIN_MALLOC(). grn_plugin_mutex_open() returns NULL if sufficient + memory is not available. + +.. c:function:: void grn_plugin_mutex_close(grn_ctx *ctx, grn_plugin_mutex *mutex) + + grn_plugin_mutex_close() finalizes an object of grn_plugin_mutex and then + frees memory allocated for that object. + +.. c:function:: void grn_plugin_mutex_lock(grn_ctx *ctx, grn_plugin_mutex *mutex) + + grn_plugin_mutex_lock() locks a mutex object. If the object is already + locked, the calling thread waits until the object will be unlocked. + +.. c:function:: void grn_plugin_mutex_unlock(grn_ctx *ctx, grn_plugin_mutex *mutex) + + grn_plugin_mutex_unlock() unlocks a mutex object. grn_plugin_mutex_unlock() + should not be called for an unlocked object. + +.. c:function:: grn_obj *grn_plugin_proc_alloc(grn_ctx *ctx, grn_user_data *user_data, grn_id domain, grn_obj_flags flags) + + grn_plugin_proc_alloc() allocates a `grn_obj` object. + You can use it in function that is registered as GRN_PROC_FUNCTION. + .. c:function:: grn_obj grn_plugin_proc_get_var(grn_ctx *ctx, grn_user_data *user_data, const char *name, int name_size) It gets a variable value from `grn_user_data` by specifying the variable name. @@ -32,7 +102,28 @@ Reference :param offset: The offset position of the variable. :return: A variable value on success, NULL otherwise. -.. c:function:: grn_rc grn_plugin_expr_var_init(grn_ctx *ctx, grn_expr_var *var, const char *name, int name_size); +.. c:function:: const char *grn_plugin_win32_base_dir(void) + + grn_plugin_win32_base_dir() returns the groonga install directory. + The install directory is computed from the directory that has + `groonga.dll`. You can use the directory to generate install + directory aware path. + It only works on Windows. It returns `NULL` on other platforms. + +.. c:function:: int grn_plugin_charlen(grn_ctx *ctx, const char *str_ptr, unsigned int str_length, grn_encoding encoding) + + grn_plugin_charlen() returns the length (#bytes) of the first character + in the string specified by `str_ptr` and `str_length`. If the starting bytes + are invalid as a character, grn_plugin_charlen() returns 0. See + grn_encoding in "groonga.h" for more details of `encoding`. + +.. c:function:: int grn_plugin_isspace(grn_ctx *ctx, const char *str_ptr, unsigned int str_length, grn_encoding encoding) + + grn_plugin_isspace() returns the length (#bytes) of the first character + in the string specified by `str_ptr` and `str_length` if it is a space + character. Otherwise, grn_plugin_isspace() returns 0. + +.. c:function:: grn_rc grn_plugin_expr_var_init(grn_ctx *ctx, grn_expr_var *var, const char *name, int name_size) It initializes a `grn_expr_var`. Modified: include/groonga/plugin.h (+0 -96) =================================================================== --- include/groonga/plugin.h 2014-06-20 23:54:27 +0900 (9c77a66) +++ include/groonga/plugin.h 2014-06-21 10:46:38 +0900 (98676ac) @@ -51,34 +51,13 @@ GRN_API void *grn_plugin_realloc(grn_ctx *ctx, void *ptr, size_t size, GRN_API void grn_plugin_free(grn_ctx *ctx, void *ptr, const char *file, int line, const char *func); -/* - GRN_PLUGIN_MALLOC() allocates `size' bytes and returns a pointer to the - allocated memory space. Note that the memory space is associated with `ctx'. - */ #define GRN_PLUGIN_MALLOC(ctx, size) \ grn_plugin_malloc((ctx), (size), __FILE__, __LINE__, __FUNCTION__) -/* - GRN_PLUGIN_REALLOC() resizes the memory space pointed to by `ptr' or - allocates a new memory space of `size' bytes. GRN_PLUGIN_REALLOC() returns - a pointer to the memory space. The contents is unchanged or copied from the - old memory space to the new memory space. - */ #define GRN_PLUGIN_REALLOC(ctx, ptr, size) \ grn_plugin_realloc((ctx), (ptr), (size), __FILE__, __LINE__, __FUNCTION__) -/* - GRN_PLUGIN_FREE() frees a memory space allocated by GRN_PLUGIN_MALLOC() or - GRN_PLUGIN_REALLOC(). This means that `ptr' must be a pointer returned by - GRN_PLUGIN_MALLOC() or GRN_PLUGIN_REALLOC(). - */ #define GRN_PLUGIN_FREE(ctx, ptr) \ grn_plugin_free((ctx), (ptr), __FILE__, __LINE__, __FUNCTION__) -/* - GRN_PLUGIN_LOG() reports a log of `level'. Its error message is generated - from the varying number of arguments, in which the first one is the format - string and the rest are its arguments. See grn_log_level in "groonga.h" for - more details of `level'. - */ #define GRN_PLUGIN_LOG(ctx, level, ...) \ GRN_LOG((ctx), (level), __VA_ARGS__) @@ -110,27 +89,11 @@ GRN_API void grn_plugin_logtrace(grn_ctx *ctx, grn_log_level level); grn_plugin_logtrace(ctx, level); \ } while (0) -/* - GRN_PLUGIN_ERROR() reports an error of `error_code'. Its error message is - generated from the varying number of arguments, in which the first one is the - format string and the rest are its arguments. See grn_rc in "groonga.h" for - more details of `error_code'. - */ #define GRN_PLUGIN_ERROR(ctx, error_code, ...) \ GRN_PLUGIN_SET_ERROR(ctx, GRN_LOG_ERROR, error_code, __VA_ARGS__) -/* - grn_plugin_mutex is available to make a critical section. See the - following functions. - */ typedef struct _grn_plugin_mutex grn_plugin_mutex; -/* - grn_plugin_mutex_open() returns a pointer to a new object of - grn_plugin_mutex. Memory for the new object is obtained with - GRN_PLUGIN_MALLOC(). grn_plugin_mutex_open() returns NULL if sufficient - memory is not available. - */ GRN_API grn_plugin_mutex *grn_plugin_mutex_open(grn_ctx *ctx); /* @@ -139,10 +102,6 @@ GRN_API grn_plugin_mutex *grn_plugin_mutex_open(grn_ctx *ctx); */ GRN_API grn_plugin_mutex *grn_plugin_mutex_create(grn_ctx *ctx); -/* - grn_plugin_mutex_close() finalizes an object of grn_plugin_mutex and then - frees memory allocated for that object. - */ GRN_API void grn_plugin_mutex_close(grn_ctx *ctx, grn_plugin_mutex *mutex); /* @@ -151,88 +110,33 @@ GRN_API void grn_plugin_mutex_close(grn_ctx *ctx, grn_plugin_mutex *mutex); */ GRN_API void grn_plugin_mutex_destroy(grn_ctx *ctx, grn_plugin_mutex *mutex); -/* - grn_plugin_mutex_lock() locks a mutex object. If the object is already - locked, the calling thread waits until the object will be unlocked. - */ GRN_API void grn_plugin_mutex_lock(grn_ctx *ctx, grn_plugin_mutex *mutex); -/* - grn_plugin_mutex_unlock() unlocks a mutex object. grn_plugin_mutex_unlock() - should not be called for an unlocked object. - */ GRN_API void grn_plugin_mutex_unlock(grn_ctx *ctx, grn_plugin_mutex *mutex); -/* - grn_plugin_proc_alloc() allocates a `grn_obj` object. - You can use it in function that is registered as GRN_PROC_FUNCTION. - */ GRN_API grn_obj *grn_plugin_proc_alloc(grn_ctx *ctx, grn_user_data *user_data, grn_id domain, grn_obj_flags flags); -/* - grn_plugin_proc_get_var() gets a variable from user_data by name. - - If `name_size` is negative, `name` must be - NUL-terminated. `name_size` is computed by `strlen(name)` for the case. -*/ - GRN_API grn_obj *grn_plugin_proc_get_var(grn_ctx *ctx, grn_user_data *user_data, const char *name, int name_size); -/* - grn_plugin_proc_get_var_by_offset() gets a variable from user_data by offset. -*/ - GRN_API grn_obj *grn_plugin_proc_get_var_by_offset(grn_ctx *ctx, grn_user_data *user_data, unsigned int offset); -/* - grn_plugin_win32_base_dir() returns the groonga install directory. - The install directory is computed from the directory that has - `groonga.dll`. You can use the directory to generate install - directory aware path. - - It only works on Windows. It returns `NULL` on other platforms. - */ GRN_API const char *grn_plugin_win32_base_dir(void); -/* - grn_plugin_charlen() returns the length (#bytes) of the first character - in the string specified by `str_ptr' and `str_length'. If the starting bytes - are invalid as a character, grn_plugin_charlen() returns 0. See - grn_encoding in "groonga.h" for more details of `encoding' - */ GRN_API int grn_plugin_charlen(grn_ctx *ctx, const char *str_ptr, unsigned int str_length, grn_encoding encoding); -/* - grn_plugin_isspace() returns the length (#bytes) of the first character - in the string specified by `str_ptr' and `str_length' if it is a space - character. Otherwise, grn_plugin_isspace() returns 0. - */ GRN_API int grn_plugin_isspace(grn_ctx *ctx, const char *str_ptr, unsigned int str_length, grn_encoding encoding); -/* - grn_plugin_expr_var_init() initializes a grn_expr_var. - - If `name_size` is negative, `name` must be - NUL-terminated. `name_size` is computed by `strlen(name)` for the case. -*/ - GRN_API grn_rc grn_plugin_expr_var_init(grn_ctx *ctx, grn_expr_var *var, const char *name, int name_size); -/* - grn_plugin_command_create() creates a command. - - If `name_size` is negative, `name` must be - NUL-terminated. `name_size` is computed by `strlen(name)` for the case. -*/ GRN_API grn_obj * grn_plugin_command_create(grn_ctx *ctx, const char *name, int name_size, -------------- next part -------------- HTML����������������������������...Download