Журналирование вызовов API

C3D Solver позволяет для конкретной системы ограничений GCE_system записать всю историю вызовов API, включая исходные параметры и возвращаемые значения вызванных функций. Результатом записи будет файл журнала, который в дальнейшем может быть использован разработчиками геометрического ядра C3D для отладки и тестирования функций C3D Solver. Устройство журнала

Файл журнала имеет текстовый формат, основанный на простом синтаксисе S-выражений. Любая функция API, вызванная для конкретной системы ограничений, фиксируется в журнале в следующем виде:

(GCE_Func (arg list)(returned value)),  

где GCE_Func – имя вызванной GCE-функции, (arg list) – список аргументов функции, (returned value) – возвращаемое значение.

Например, так выглядит запись вызова, создающего окружность с центром в начале координат и радиусом 2.5:

(GCE_AddCircle ((0.0 0.0) 2.5) #1)

Окружность получила символический идентификатор #1, который является возвращаемым значением функции GCE_AddCircle.

Журнал фактически является записью сеанса работы с конкретной системой ограничений на языке, который может быть интерпретирован специальными средствами, которыми располагает разработчик C3D Solver. Также журнал может быть отредактирован вручную или упрощен, если для достижения определенной ситуации не требуются все вызовы.

Включение режима журналирования

Чтобы включить режим записи журнала системы ограничений, необходимо вызвать функцию

bool GCE_SetJournal(GCE_system gSys, const char * fName),   

которая для системы ограничений gSys назначит файл журнала fName. В случае успешной инициализации режима функция вернет true.

Входными параметрами метода являются:

gSys – пустая система ограничений, созданная методом GCE_CreateSystem,
fName – строка, задающая полный путь к файлу. Например: «..Journals\sample.jrn»

После включения журналирования будет осуществляться запись информации о всех обращениях к API С3D Solver, адресованных системе ограничений gSys.

Внимание: файл журнала будет готов только после завершения сеанса работы с системой ограничений, а именно сразу после вызова GCE_RemoveSystem().

Пример кода демонстрирующего запись сеанса работы системы ограничений в журнал приведен ниже:

GCE_system gSys = GCE_CreateSystem();
// Switch on journalling for the constraint system.
GCE_SetJournal(gSys, "C:\\Logs\\gce_sample.jrn");
// Make some calls of C3D Solver ...
GCE_point p1Val, p2Val; // Coordinates of two points = (1,1) and (2,2)
p1Val.x = p1Val.y = 1.0;
p2Val.x = p2Val.y = 2.0;
geom_item pnt[2] = { GCE_AddPoint(gSys, p1Val), GCE_AddPoint(gSys, p2Val) };
GCE_AddCoincidence(gSys, pnt);
// ...
// ...
GCE_Evaluate(gSys);
// Finalize the constraint system
GCE_RemoveSystem(gSys);
// The journal file is ready!   

Замечание

Журналирование нужно только для отладочных целей, поэтому рекомендуется включать её только в режиме отладки. Не следует оставлять журналирование включенным для продуктовой (release) или рабочей версии приложения, т.к. это может приводить к напрасному расходованию ресурсов времени и памяти.

Отладка и тестирование

Журналирование дает возможность разработчику геометрического ядра отлаживать функций C3D Solver путем воспроизведения журнала вызовов, записанного при работе в приложении. Данный способ использует тот факт, что внутреннее состояние системы ограничений полностью определяется последовательностью вызовов API, поэтому достаточно повторить ту же последовательность вызовов с теми же данными, чтобы полностью воспроизвести проблему, возникшую при эксплуатации решателя приложением.

Обширная коллекция журналов образует базу тестовых примеров, которая является неотъемлемым инструментом для развития и контроля качества модуля C3D Solver. Каждая ревизия C3D Solver проверяется на тестовой базе журналов, что гарантирует сохранение результатов всех ранее сделанных исправлений и усовершенствований.

Таким образом, чтобы получить консультацию или решить проблемную ситуацию, связанную со встраиванием C3D Solver в приложение, достаточно временно включить режим журналирования, выполнить интересующий сценарий действий и переслать полученный файл с необходимыми комментариями или вопросами в техническую поддержку C3D Labs. После исправления ошибки соответствующий журнал добавляется в базу тестовых примеров.