API Call Journalling

C3D Solver permits to record the entire API call log, including the original parameters and the parameters returned by called functions for any specific GCE_system constraint system. The result will be a log file that can be later used by C3D geometric core developers to debug and test C3D Solver functions.

Log structure

The log file is a text file, it uses simple S-expression syntax that permits to record any nested and list-based data structures. Any API function called for a specific constraint system is recorded in the log file in the following form:

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

where GCE_Func is the name of the called GCE function, (arg list) is a list of function arguments, and (returned value) is the returned value.

For example, this is how a log of a call that creates a circle with a center in the coordinate system origin and radius 2.5 looks like:

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

The circle has received symbolic identifier #1, which is the value returned by the GCE_AddCircle function.

The log is actually a session record for a specific constraint system written in a language that can be interpreted by special tools available to C3D Solver developers. You can manually edit or simplify a log, if not all calls are required to achieve a specific result.

Enabling logging mode.

In order to enable the constraint system logging, you need to call

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

that will assign the fName log file to the gSys constraint system. If logging mode was successfully initialized, then the function returns true.

The method input parameters are:

• gSys is an empty constraint system created by the GCE_CreateSystem method,

• fName is a string with a complete file path. Example: “..Journals\sample.jrn”

If logging is enabled, then data about all API C3D Solver calls to the gSys constraint system are recorded.

Warning! The log file will be ready only when a session of work with the constraint system is finished, i.e. immediately after calling the GCE_RemoveSystem() method.

Code example.

An example of code that demonstrates how constraint system session data are recorded in the log is shown below.

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!

Note. Logging is required only for debugging, so it is recommended to enable it only in debug mode. It is not recommended to leave logging enabled for application release version or production version, as it can result in extra time and memory overheads.

Debugging and testing. Logging permit geometric core developers to debug C3D Solver functions by recreating the call log created when the application worked. This method is based on the fact that the internal state of a constraint system is completely defined by API call sequence, therefore it is possible to repeat the same call sequence with the same data to fully recreate a problem arising when the application calls the solver.

An extensive collection of logs forms a test case base that is an essential tool for C3D Solver module development and quality control. Each C3D Solver revision is checked on a test base of logs to guarantee that none of previous patches and upgrades was lost.

Therefore, in order to receive consulting or resolve a problem related to embedding C3D Solver in an application, you need to enable logging mode for a while, execute the required sequence of actions, and send the resulting file with necessary comments or questions to C3D Labs technical support. When the error is fixed, the corresponding log is added in test case base.