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 для удаления.

			Справочное описание GLib
Начало \| Описание