Navigation Menu

Skip to content

Commit

Permalink
doc:move plugin API documents from plugin.h to Sphinx text
Browse files Browse the repository at this point in the history
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
  • Loading branch information
naoa committed Jun 21, 2014
1 parent 22ca12c commit ac9228c
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 97 deletions.
93 changes: 92 additions & 1 deletion doc/source/reference/api/plugin.rst
Expand Up @@ -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.
Expand All @@ -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`.
Expand Down
96 changes: 0 additions & 96 deletions include/groonga/plugin.h
Expand Up @@ -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__)

Expand Down Expand Up @@ -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);

/*
Expand All @@ -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);

/*
Expand All @@ -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,
Expand Down

0 comments on commit ac9228c

Please sign in to comment.