7.20.3. Plugin

7.20.3.1. Summary

Groonga supports plugin. You can create a new plugin with the following API.

TOOD: Describe about how to create the minimum plugin here or create a tutorial about it.

7.20.3.2. Reference

grn_rc GRN_PLUGIN_INIT(grn_ctx *ctx)

grn_rc GRN_PLUGIN_REGISTER(grn_ctx *ctx)

grn_rc GRN_PLUGIN_FIN(grn_ctx *ctx)

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.

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.

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().

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.

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.

grn_plugin_mutex

grn_plugin_mutex is available to make a critical section. See the following functions.

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.

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.

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.

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.

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.

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.

Parameters:

• name -- The variable name.
• name_size -- The number of bytes of name. If name_size is negative, name must be NUL-terminated. name_size is computed by strlen(name) for the case.

Returns:

A variable value on success, NULL otherwise.

grn_obj *grn_plugin_proc_get_var_by_offset(grn_ctx *ctx, grn_user_data *user_data, unsigned int offset)

It gets a variable value from grn_user_data by specifying the offset position of the variable.

Parameters:

• offset -- The offset position of the variable.

Returns:

A variable value on success, NULL otherwise.

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.

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.

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.

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.

Parameters:

• var -- The pointer of grn_expr_var object to be initialized.
• name -- The name of grn_expr_var object to be initialized.
• name_size -- The number of bytes of name. If name_size is negative, name must be NUL-terminated. name_size is computed by strlen(name) for the case.

Returns:

GRN_SUCCESS. It doesn't fail.

grn_obj * grn_plugin_command_create(grn_ctx *ctx, const char *name, int name_size, grn_proc_func func, unsigned int n_vars, grn_expr_var *vars)

It creates a command.

Parameters:

• name -- The proc name of the command to be created.
• name_size -- The number of bytes of name. If name_size is negative, name must be NUL-terminated. name_size is computed by strlen(name) for the case.
• func -- The function name to be called by the created command.
• n_vars -- The number of the variables of the command to create.
• vars -- The pointer of initialized grn_expr_var object.

Returns:

The created command object if it creates a command successfully, NULL otherwise. See ctx for error details.