Hook Functions

Hook Functions — поддержка для манипулирования списками hook-функций.

Краткое описание

#include <glib.h> GHookList; void (*GHookFinalizeFunc) (GHookList *hook_list, GHook *hook); GHook; void (*GHookFunc) (gpointer data); gboolean (*GHookCheckFunc) (gpointer data); void g_hook_list_init (GHookList *hook_list, guint hook_size); void g_hook_list_invoke (GHookList *hook_list, gboolean may_recurse); void g_hook_list_invoke_check (GHookList *hook_list, gboolean may_recurse); void g_hook_list_marshal (GHookList *hook_list, gboolean may_recurse, GHookMarshaller marshaller, gpointer marshal_data); void (*GHookMarshaller) (GHook *hook, gpointer marshal_data); void g_hook_list_marshal_check (GHookList *hook_list, gboolean may_recurse, GHookCheckMarshaller marshaller, gpointer marshal_data); gboolean (*GHookCheckMarshaller) (GHook *hook, gpointer marshal_data); void g_hook_list_clear (GHookList *hook_list); GHook* g_hook_alloc (GHookList *hook_list); #define g_hook_append ( hook_list, hook ) void g_hook_prepend (GHookList *hook_list, GHook *hook); void g_hook_insert_before (GHookList *hook_list, GHook *sibling, GHook *hook); void g_hook_insert_sorted (GHookList *hook_list, GHook *hook, GHookCompareFunc func); gint (*GHookCompareFunc) (GHook *new_hook, GHook *sibling); gint g_hook_compare_ids (GHook *new_hook, GHook *sibling); GHook* g_hook_get (GHookList *hook_list, gulong hook_id); GHook* g_hook_find (GHookList *hook_list, gboolean need_valids, GHookFindFunc func, gpointer data); gboolean (*GHookFindFunc) (GHook *hook, gpointer data); GHook* g_hook_find_data (GHookList *hook_list, gboolean need_valids, gpointer data); GHook* g_hook_find_func (GHookList *hook_list, gboolean need_valids, gpointer func); GHook* g_hook_find_func_data (GHookList *hook_list, gboolean need_valids, gpointer func, gpointer data); GHook* g_hook_first_valid (GHookList *hook_list, gboolean may_be_in_call); GHook* g_hook_next_valid (GHookList *hook_list, GHook *hook, gboolean may_be_in_call); enum GHookFlagMask; #define G_HOOK_FLAGS (hook) #define G_HOOK_FLAG_USER_SHIFT #define G_HOOK (hook) #define G_HOOK_IS_VALID (hook) #define G_HOOK_ACTIVE (hook) #define G_HOOK_IN_CALL (hook) #define G_HOOK_IS_UNLINKED (hook) GHook* g_hook_ref (GHookList *hook_list, GHook *hook); void g_hook_unref (GHookList *hook_list, GHook *hook); void g_hook_free (GHookList *hook_list, GHook *hook); gboolean g_hook_destroy (GHookList *hook_list, gulong hook_id); void g_hook_destroy_link (GHookList *hook_list, GHook *hook);

Описание

GHookList, GHook и связанные с ними функции обеспечивают поддержку для списков hook-функций. Функции могут быть добавлены и удалены из списков, а список hook-функций может быть вызван.

Детали

GHookList

typedef struct { gulong seq_id; guint hook_size : 16; guint is_setup : 1; GHook *hooks; gpointer dummy3; GHookFinalizeFunc finalize_hook; gpointer dummy[2]; } GHookList;

Структура GHookList представляет список hook-функций.

gulong seq_id; следующий свободный GHook id.
guint hook_size : 16; размер элементов GHookList, в байтах.
guint is_setup : 1; 1 если GHookList была инициализирована.
GHook *hooks; первый элемент GHook в списке.
gpointer dummy3;
GHookFinalizeFunc finalize_hook; функция вызываемая для завершающего элемента GHook. По умолчанию вызывается разрушающая функция обработчика прерывания.
gpointer dummy[2];

GHookFinalizeFunc ()

void (*GHookFinalizeFunc) (GHookList *hook_list, GHook *hook);

Определяет тип функции вызываемой для завершающего прерывания в списке прерываний.

hook_list : GHookList.
hook : завершающее прерывание в hook_list.

GHook

typedef struct { gpointer data; GHook *next; GHook *prev; guint ref_count; gulong hook_id; guint flags; gpointer func; GDestroyNotify destroy; } GHook;

Структура GHook представляет единственную hook-функцию в GHookList.

gpointer data; данные помещаемые в функцию когда вызвано прерывание.
GHook *next; указатель на следующее прерывание в списке.
GHook *prev; указатель на предыдущее прерывание в списке.
guint ref_count; количество ссылок на это прерывание.
gulong hook_id; id этого прерывания, который уникален внутри этого списка.
guint flags; флаги устанавливаемые для этого прерывания. Смотрите предопределённые флаги в GHookFlagMask.
gpointer func; функция вызываемая при возникновении этого прерывания. Возможными сигнатурами для этой функции являются GHookFunc и GHookCheckFunc.
GDestroyNotify destroy; по умолчанию finalize_hook функция GHookList вызывает этот элемент прерывания для завершения.

GHookFunc ()

void (*GHookFunc) (gpointer data);

Определяет тип hook-функции которую может вызвать g_hook_list_invoke().

data : поле данных GHook помещаемых в hook-функцию.

GHookCheckFunc ()

gboolean (*GHookCheckFunc) (gpointer data);

Определяет тип функции которая может быть вызвана g_hook_list_invoke_check().

data : поле данных GHook помещаемых в hook-функцию.
Возвращает : FALSE если GHook должен быть разрушен.

g_hook_list_init ()

void g_hook_list_init (GHookList *hook_list, guint hook_size);

Инициализирует GHookList. Должна вызываться после использования GHookList.

hook_list : GHookList.
hook_size : размер каждого элемента в GHookList, обычно sizeof (GHook).

g_hook_list_invoke ()

void g_hook_list_invoke (GHookList *hook_list, gboolean may_recurse);

Вызывает все функции GHook в GHookList.

hook_list : GHookList.
may_recurse : TRUE если функции уже запущенные (например в другом потоке) могут быть вызваны. Если установить в FALSE, они пропускаются.

g_hook_list_invoke_check ()

void g_hook_list_invoke_check (GHookList *hook_list, gboolean may_recurse);

Вызывает все GHook функции в GHookList. Любая функция которая возвращает TRUE удаляется из GHookList.

hook_list : GHookList.
may_recurse : TRUE если функции которые уже выполняются (например в другом потоке) могут быть вызваны. Если установлено в FALSE, они пропускаются.

g_hook_list_marshal ()

void g_hook_list_marshal (GHookList *hook_list, gboolean may_recurse, GHookMarshaller marshaller, gpointer marshal_data);

Вызывает функцию в каждом допустимом GHook.

hook_list : GHookList.
may_recurse : TRUE если текущие выполняемые hooks (например в другом потоке) рассматриваются как допустимые. Если установлено в FALSE, они пропускаются.
marshaller : функция вызываемая для каждого элемента GHook.
marshal_data : данные для помещения в marshaller.

GHookMarshaller ()

void (*GHookMarshaller) (GHook *hook, gpointer marshal_data);

Определяет тип функции используемой в g_hook_list_marshal().

hook : GHook.
marshal_data : пользовательские данные.

g_hook_list_marshal_check ()

void g_hook_list_marshal_check (GHookList *hook_list, gboolean may_recurse, GHookCheckMarshaller marshaller, gpointer marshal_data);

Вызывает функцию для каждого допустимого GHook и уничтожает его если функция возвращает FALSE.

hook_list : GHookList.
may_recurse : TRUE если hooks выполняемые в текущий момент (например в другом потоке) рассматриваются как допустимые. Если установлено в FALSE, они пропускаются.
marshaller : функция вызываемая для каждого элемента GHook.
marshal_data : данные помещаемые в marshaller.

GHookCheckMarshaller ()

gboolean (*GHookCheckMarshaller) (GHook *hook, gpointer marshal_data);

Определяет тип функции используемой в g_hook_list_marshal_check().

hook : GHook.
marshal_data : пользовательские данные.
Возвращает : FALSE если hook должен быть уничтожен.

g_hook_list_clear ()

void g_hook_list_clear (GHookList *hook_list);

Удаляет все GHook элементы из GHookList.

hook_list : GHookList.

g_hook_alloc ()

GHook* g_hook_alloc (GHookList *hook_list);

Распределяет место для GHook и инициализирует его.

hook_list : GHookList.
Возвращает : новый GHook.

g_hook_append()

#define g_hook_append( hook_list, hook )

Добавляет GHook в конец GHookList.

hook_list : GHookList.
hook : GHook для добавления в конец hook_list.

g_hook_prepend ()

void g_hook_prepend (GHookList *hook_list, GHook *hook);

Добавляет GHook в начало GHookList.

hook_list : GHookList.
hook : GHook для добавления в начало hook_list.

g_hook_insert_before ()

void g_hook_insert_before (GHookList *hook_list, GHook *sibling, GHook *hook);

Вставляет GHook в GHookList, перед полученным GHook.

hook_list : GHookList.
sibling : GHook перед которым вставляется новый GHook.
hook : the GHook для вставки.

g_hook_insert_sorted ()

void g_hook_insert_sorted (GHookList *hook_list, GHook *hook, GHookCompareFunc func);

Вставляет GHook в GHookList, сортируя полученной функцией.

hook_list : GHookList.
hook : GHook для вставки.
func : функция сравнения используемая для сортировки элементов GHook.

GHookCompareFunc ()

gint (*GHookCompareFunc) (GHook *new_hook, GHook *sibling);

Определяет тип функции используемой для сравнения GHook элементов в g_hook_insert_sorted().

new_hook : GHook для вставки.
sibling : GHook для сравнения с new_hook.
Возвращает : значение <= 0 если new_hook должен быть перед sibling.

g_hook_compare_ids ()

gint g_hook_compare_ids (GHook *new_hook, GHook *sibling);

Сравнивает ids двух GHook элементов, возвращает отрицательное значение если второй id больше первого.

new_hook : GHook.
sibling : GHook для сравнения с new_hook.
Возвращает : значение <= 0 если id sibling >= id new_hook.

g_hook_get ()

GHook* g_hook_get (GHookList *hook_list, gulong hook_id);

Возвращает GHook с полученным id, или NULL если он не найден.

hook_list : GHookList.
hook_id : hook id.
Возвращает : GHook с полученным id, или NULL если он не найден.

g_hook_find ()

GHook* g_hook_find (GHookList *hook_list, gboolean need_valids, GHookFindFunc func, gpointer data);

Ищет GHook в GHookList используя функцию для проверочного сравнения.

hook_list : GHookList.
need_valids : TRUE если GHook которые были разрушены должны быть пропущены.
func : функция вызываемая для каждого GHook, которая должна возвращать TRUE когда GHook найден.
data : данные помещаемые в func.
Возвращает : найденый GHook или NULL если соответствующий GHook не найден.

GHookFindFunc ()

gboolean (*GHookFindFunc) (GHook *hook, gpointer data);

Определяет тип функции помещаемой в g_hook_find().

hook : GHook.
data : пользовательские данные помещаемые в g_hook_find_func().
Возвращает : TRUE если требуемый GHook был найден.

g_hook_find_data ()

GHook* g_hook_find_data (GHookList *hook_list, gboolean need_valids, gpointer data);

Находит GHook в GHookList с полученными данными.

hook_list : GHookList.
need_valids : TRUE если GHook элементы которые были разрушены должны быть пропущены.
data : данные для поиска.
Возвращает : GHook с полученными data или NULL если нет соответсвующего GHook.

g_hook_find_func ()

GHook* g_hook_find_func (GHookList *hook_list, gboolean need_valids, gpointer func);

Находит GHook в GHookList с полученной функцией.

hook_list : GHookList.
need_valids : TRUE если GHook элементы которые были разрушены должны быть пропущены.
func : функция для поиска.
Возвращает : GHook с полученной func или NULL если соответсвующий GHook не найден.

g_hook_find_func_data ()

GHook* g_hook_find_func_data (GHookList *hook_list, gboolean need_valids, gpointer func, gpointer data);

Находит GHook в GHookList с полученной функцией и данными.

hook_list : GHookList.
need_valids : TRUE если GHook элементы которые были разрушены должны быть пропущены.
func : искомая функция.
data : искомые данные.
Возвращает : GHook с полученной func и data или NULL если соответствующий GHook не найден.

g_hook_first_valid ()

GHook* g_hook_first_valid (GHookList *hook_list, gboolean may_be_in_call);

Возвращает первый GHook в GHookList который небыл разрушен. Количество ссылок для GHook увеличивается, поэтому вы должны вызвать g_hook_unref() для его восстановления когда он больше не нужен. (Или вызвать g_hook_next_valid() если вы двигаетесь через GHookList.)

hook_list : GHookList.
may_be_in_call : TRUE если выполняемые в данный момент hooks (например в другом потоке) рассматриваются как допустимые. Если установить в FALSE, они пропускаются.
Возвращает : первый допустимый GHook, или NULL если нет допустимых.

g_hook_next_valid ()

GHook* g_hook_next_valid (GHookList *hook_list, GHook *hook, gboolean may_be_in_call);

Возвращает следующий GHook в GHookList который небыл разрушен. Количество ссылок для GHook уменьшается, поэтому вы должны вызвать g_hook_unref() для восстановления когда он больше не нужен. (Или вызывать g_hook_next_valid() пока не вернётся NULL.)

hook_list : GHookList.
hook : текущий GHook.
may_be_in_call : TRUE если hooks выполняемые в текущий момент (например в другом потоке) рассматриваются как допустимые. Если установить в FALSE, они пропускаются.
Возвращает : следующий допустимый GHook, или NULL если нет допустимых.

enum GHookFlagMask

typedef enum { G_HOOK_FLAG_ACTIVE = 1 << 0, G_HOOK_FLAG_IN_CALL = 1 << 1, G_HOOK_FLAG_MASK = 0x0f } GHookFlagMask;

Флаги используемые внутренней реализацией GHook.

G_HOOK_FLAG_ACTIVE устанавливается если hook небыл разрушен.
G_HOOK_FLAG_IN_CALL устанавливается если hook выполняется в текущий момент.
G_HOOK_FLAG_MASK Маска покрывающая все биты зарезервированные для hook флагов; смотрите G_HOOK_FLAGS_USER_SHIFT

G_HOOK_FLAGS()

#define G_HOOK_FLAGS(hook) (G_HOOK (hook)->flags)

Возвращает флаги hook.

hook : GHook.

G_HOOK_FLAG_USER_SHIFT

#define G_HOOK_FLAG_USER_SHIFT (4)

Позиция первого бита который не зарезервирован для внутреннего использования реализацией GHook, то есть 1 << G_HOOK_FLAG_USER_SHIFT это первый бит который может использоваться для определённых приложением флагов.

G_HOOK()

#define G_HOOK(hook) ((GHook*) (hook))

Приводит указатель на GHook*.

hook : указатель.

G_HOOK_IS_VALID()

#define G_HOOK_IS_VALID(hook)

Возвращает TRUE если GHook допустим, то есть он в GHookList, он активен и он был разрушен.

hook : GHook.
Возвращает : TRUE если GHook допустим.

G_HOOK_ACTIVE()

#define G_HOOK_ACTIVE(hook)

Возвращает TRUE если GHook активен, который обычно TRUE пока GHook разрушен.

hook : GHook.
Возвращает : TRUE если GHook активен.

G_HOOK_IN_CALL()

#define G_HOOK_IN_CALL(hook)

Возвращает TRUE если GHook функция в текущий момент выполняется.

hook : GHook.
Возвращает : TRUE если GHook функция в текущий момент выполняется.

G_HOOK_IS_UNLINKED()

#define G_HOOK_IS_UNLINKED(hook)

Возвращает TRUE если GHook не находится в GHookList.

hook : GHook.
Возвращает : TRUE если GHook не находится в GHookList.

g_hook_ref ()

GHook* g_hook_ref (GHookList *hook_list, GHook *hook);

Увеличивает количество ссылок для GHook.

hook_list : GHookList.
hook : GHook для увеличения количества ссылок.
Возвращает : помещённый hook (Начиная с версии 2.6)

g_hook_unref ()

void g_hook_unref (GHookList *hook_list, GHook *hook);

Уменьшает количество ссылок GHook. Если количество ссылок равно 0, GHook удаляется из GHookList и вызывается g_hook_free() для его освобождения.

hook_list : GHookList.
hook : GHook для отмены ссылки.

g_hook_free ()

void g_hook_free (GHookList *hook_list, GHook *hook);

Вызывает GHookList hook_free функцию если она существует и освобождает память распределённую для GHook.

hook_list : GHookList.
hook : освобождаемая GHook.

g_hook_destroy ()

gboolean g_hook_destroy (GHookList *hook_list, gulong hook_id);

Разрушает GHook, получая его ID.

hook_list : GHookList.
hook_id : hook ID.
Возвращает : TRUE если GHook был найден в GHookList и разрушен.

g_hook_destroy_link ()

void g_hook_destroy_link (GHookList *hook_list, GHook *hook);

Удаляет один GHook из GHookList, маркируя его как неактивный и вызывая для него g_hook_unref().

hook_list : GHookList.
hook : GHook для удаления.