Функции для работы с атрибутными объектами потоков трассировки

Согласно стандарту POSIX-2001, система трассировки строится в объектно-ориентированном стиле. Структура большинства используемых объектов скрыта от приложения, поэтому требуется довольно много относительно мелких функций – конструкторов, селекторов, итераторов.

Для систематического рассмотрения целесообразно представить множество функций трассировки в виде трехуровневой иерархии. Разветвление на верхнем уровне производится в соответствии с ролью процесса (трассирующий, трассируемый, анализирующий), а на втором уровне – в соответствии с классом обслуживаемых объектов (потоки и их атрибутные объекты, журналы, события и т.д.). На третьем уровне располагаются функциональные группы, предназначенные для выполнения определенных операций (создание/уничтожение, опрос/изменение и т.п.) над объектами определенных классов.

Чтобы получить общее представление о функциях трассировки, рассмотрим сначала два верхних уровня описанной иерархии.

Трассирующий процесс управляет ресурсами, ассоциированными с потоками трассировки, а именно:

атрибутными объектами потоков трассировки;
собственно потоками трассировки;
журналами трассировки;
идентификаторами типов событий;
фильтрами.

Трассируемый процесс имеет дело со следующими объектами:

события;
идентификаторы типов событий;
точки трассировки.

Анализирующий процесс читает:

потоки трассировки;
журналы;
события;
идентификаторы типов событий.

Перейдем к детальному рассмотрению функций трассировки.

Для создания и уничтожения атрибутных объектов потоков трассировки служат функции posix_trace_attr_init() и posix_trace_attr_destroy() (см. листинг 8.1).

#include <trace.h> int posix_trace_attr_init ( trace_attr_t *attr); int posix_trace_attr_destroy ( trace_attr_t *attr);

Листинг 8.1. Описание функций создания и уничтожения атрибутных объектов потоков трассировки. (html, txt)

Функция posix_trace_attr_init() инициализирует атрибутный объект подразумеваемыми значениями для всех атрибутов, используемых реализацией. Отметим, что два атрибута – имя версии системы трассировки и разрешающая способность часов, с помощью которых проставляются временные штампы, – доступны только на чтение.

Трассирующий процесс управляет ресурсами, ассоциированными с потоками трассировки, а именно:

атрибутными объектами потоков трассировки;
собственно потоками трассировки;
журналами трассировки;
идентификаторами типов событий;
фильтрами.

Трассируемый процесс имеет дело со следующими объектами:

события;
идентификаторы типов событий;
точки трассировки.

Анализирующий процесс читает:

потоки трассировки;
журналы;
события;
идентификаторы типов событий.

Перейдем к детальному рассмотрению функций трассировки.

#include <trace.h> int posix_trace_attr_init ( trace_attr_t *attr); int posix_trace_attr_destroy ( trace_attr_t *attr);

Листинг 8.1. Описание функций создания и уничтожения атрибутных объектов потоков трассировки.

Нормальным является нулевой результат; при наличии ошибки возвращается ее номер.

Для манипулирования атрибутами, идентифицирующими поток трассировки, служат функции posix_trace_attr_getgenversion(), posix_trace_attr_getname(), posix_trace_attr_setname(), posix_trace_attr_getcreatetime() (см. листинг 8.2).

#include <trace.h> int posix_trace_attr_getgenversion ( const trace_attr_t *attr, char *genversion); int posix_trace_attr_getname ( const trace_attr_t *attr, char *tracename); int posix_trace_attr_setname ( trace_attr_t *attr, const char *tracename); #include <time.h> #include <trace.h> int posix_trace_attr_getcreatetime ( const trace_attr_t *attr, struct timespec *createtime);

Листинг 8.2. Описание функций манипулирования атрибутами, идентифицирующими поток трассировки. (html, txt)

Функции опроса копируют значения соответствующих атрибутов (имя версии системы трассировки, имя и время создания потока трассировки) из атрибутного объекта, заданного аргументом attr, в символьный массив (длина которого должна быть не меньше TRACE_NAME_MAX) или в структуру. Функция posix_trace_attr_setname() копирует имя (длина которого не должна превышать TRACE_NAME_MAX) в противоположном направлении.

Функция posix_trace_attr_getclockres() (см. листинг 8.3) позволяет опросить разрешающую способность часов, с помощью которых проставляются временные штампы.

#include <time.h> #include <trace.h> int posix_trace_attr_getclockres ( const trace_attr_t *attr, struct timespec *resolution);

Листинг 8.3. Описание функции опроса разрешающей способности часов, с помощью которых проставляются временные штампы. (html, txt)

Нормальным является нулевой результат; при наличии ошибки возвращается ее номер.

Для манипулирования атрибутами, идентифицирующими поток трассировки, служат функции posix_trace_attr_getgenversion(), posix_trace_attr_getname(), posix_trace_attr_setname(), posix_trace_attr_getcreatetime() (см. листинг 8.2).

#include <trace.h> int posix_trace_attr_getgenversion ( const trace_attr_t *attr, char *genversion); int posix_trace_attr_getname ( const trace_attr_t *attr, char *tracename); int posix_trace_attr_setname ( trace_attr_t *attr, const char *tracename); #include <time.h> #include <trace.h> int posix_trace_attr_getcreatetime ( const trace_attr_t *attr, struct timespec *createtime);

Листинг 8.2. Описание функций манипулирования атрибутами, идентифицирующими поток трассировки.

Функции опроса копируют значения соответствующих атрибутов (имя версии системы трассировки, имя и время создания потока трассировки) из атрибутного объекта, заданного аргументом attr, в символьный массив (длина которого должна быть не меньше TRACE_NAME_MAX) или в структуру. Функция posix_trace_attr_setname() копирует имя (длина которого не должна превышать TRACE_NAME_MAX) в противоположном направлении.

Функция posix_trace_attr_getclockres() (см. листинг 8.3) позволяет опросить разрешающую способность часов, с помощью которых проставляются временные штампы.

#include <time.h> #include <trace.h> int posix_trace_attr_getclockres ( const trace_attr_t *attr, struct timespec *resolution);

Листинг 8.3. Описание функции опроса разрешающей способности часов, с помощью которых проставляются временные штампы.

Поведенческие атрибуты потоков и журналов обслуживаются функциями: posix_trace_attr_getinherited(), posix_trace_attr_setinherited(), posix_trace_attr_getstreamfullpolicy(), posix_trace_attr_setstreamfullpolicy(), posix_trace_attr_getlogfullpolicy(), posix_trace_attr_setlogfullpolicy() (см. листинг 8.4).

#include <trace.h> int posix_trace_attr_getinherited ( const trace_attr_t *restrict attr, int *restrict inheritancepolicy); int posix_trace_attr_setinherited ( trace_attr_t *attr, int inheritancepolicy); int posix_trace_attr_getstreamfullpolicy ( const trace_attr_t *restrict attr, int *restrict streampolicy); int posix_trace_attr_setstreamfullpolicy ( trace_attr_t *attr, int streampolicy); int posix_trace_attr_getlogfullpolicy ( const trace_attr_t *restrict attr, int *restrict logpolicy); int posix_trace_attr_setlogfullpolicy ( trace_attr_t *attr, int logpolicy);

Листинг 8.4. Описание функций манипулирования значениями поведенческих атрибутов потоков и журналов в атрибутных объектах.

Функции posix_trace_attr_getinherited() и posix_trace_attr_setinherited() позволяют, соответственно, опросить и установить значение атрибута наследования трассировки порожденными процессами. Если значение этого атрибута равно POSIX_TRACE_INHERITED, то после вызовов fork() и/или spawn() родительский и порожденный процессы будут трассироваться параллельно с использованием общего потока трассировки. Подразумеваемое значение атрибута суть POSIX_TRACE_CLOSE_FOR_CHILD (не трассировать порожденные процессы).

Атрибут, специфицирующий правила обработки ситуации заполнения, и для потоков (функции posix_trace_attr_getstreamfullpolicy() и posix_trace_attr_setstreamfullpolicy()), и для журналов трассировки (функции posix_trace_attr_getlogfullpolicy() и posix_trace_attr_setlogfullpolicy()) может принимать следующие значения.

POSIX_TRACE_LOOP

Для потоков – продолжение трассировки с записью новых событий поверх самых старых; для журналов – сброс всех событий из потока также с записью поверх самых старых.

POSIX_TRACE_UNTIL_FULL

Для потоков – приостановка трассировки с генерацией события POSIX_TRACE_STOP. Реализация обязана возобновить трассировку (с генерацией события POSIX_TRACE_START) после очистки потока, но может сделать это и раньше, за счет повторного использования пространства, которое занимали прочитанные события. Для журналов – прекращение сброса (последним в журнал помещается событие POSIX_TRACE_STOP). События, которые не поместились в журнал, пропадают.

Для потоков трассировки еще одним возможным значением служит

POSIX_TRACE_FLUSH

Регулярно сбрасывать поток в журнал трассировки; в остальном действовать по правилам POSIX_TRACE_UNTIL_FULL.

Если с потоком ассоциирован журнал, то подразумеваемым значением данного атрибута является POSIX_TRACE_FLUSH; в противном случае – POSIX_TRACE_LOOP.

Для журналов трассировки описываемый атрибут может принимать значение

POSIX_TRACE_APPEND

Потенциально неограниченное расширение журнала.

Подразумеваемым для журналов является значение POSIX_TRACE_LOOP.

Опросить и/или установить хранящиеся в атрибутном объекте размеры событий, потоков и журналов можно с помощью функций: posix_trace_attr_getmaxdatasize(), posix_trace_attr_setmaxdatasize(), posix_trace_attr_getmaxsystemeventsize(), posix_trace_attr_getmaxusereventsize(), posix_trace_attr_getstreamsize(), posix_trace_attr_setstreamsize(), posix_trace_attr_getlogsize(), posix_trace_attr_setlogsize() (см. листинг 8.5).

#include <sys/types.h> #include <trace.h> int posix_trace_attr_getmaxdatasize ( const trace_attr_t *restrict attr, size_t *restrict maxdatasize); int posix_trace_attr_setmaxdatasize ( trace_attr_t *attr, size_t maxdatasize); int posix_trace_attr_getmaxsystemeventsize ( const trace_attr_t *restrict attr, size_t *restrict eventsize); int posix_trace_attr_getmaxusereventsize ( const trace_attr_t *restrict attr, size_t data_len, size_t *restrict eventsize); int posix_trace_attr_getstreamsize ( const trace_attr_t *restrict attr, size_t *restrict streamsize); int posix_trace_attr_setstreamsize ( trace_attr_t *attr, size_t streamsize); int posix_trace_attr_getlogsize ( const trace_attr_t *restrict attr, size_t *restrict logsize); int posix_trace_attr_setlogsize ( trace_attr_t *attr, size_t logsize);

Листинг 8.5. Описание функций манипулирования размерами событий, потоков и журналов в атрибутных объектах.

Функции posix_trace_attr_getmaxdatasize() и posix_trace_attr_setmaxdatasize() позволяют опросить и установить максимальный размер (в байтах) данных, ассоциируемых с пользовательскими событиями. Подразумеваемое значение этого атрибута зависит от реализации.

Функции posix_trace_attr_getmaxsystemeventsize() и posix_trace_attr_getmaxusereventsize() служат для опроса максимального размера системных и пользовательских событий, соответственно (во втором случае учитывается размер ассоциированных данных, определяемый значением аргумента data_len).

Функции posix_trace_attr_getstreamsize() и posix_trace_attr_setstreamsize() ведают минимальным объемом памяти, который система трассировки обязана зарезервировать в потоке для хранения событий. Накладные расходы на размещение атрибутов потока, таких как идентифицирующие данные или правила поведения, в эту величину не входят. Пока сумма максимальных размеров событий не превосходит значения данного атрибута, события должны записываться без потери информации.

Функции posix_trace_attr_getlogsize() и posix_trace_attr_setlogsize() обслуживают атрибут журнала трассировки – максимальный размер, резервируемый для хранения событий. Если правило обработки ситуации заполнения журнала определено как POSIX_TRACE_APPEND, данный атрибут игнорируется.

Содержание раздела