From 9a182337235d63a93b7276d68f27ca550b64a030 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Mon, 8 Jul 2024 10:44:09 +0800 Subject: [PATCH] doc: update document for exception helper --- doc/src/exception_helper.dox | 87 ++++++++++++++++++++++++++++++++++++ doc/src/index.dox | 2 + 2 files changed, 89 insertions(+) create mode 100644 doc/src/exception_helper.dox diff --git a/doc/src/exception_helper.dox b/doc/src/exception_helper.dox new file mode 100644 index 0000000..d409138 --- /dev/null +++ b/doc/src/exception_helper.dox @@ -0,0 +1,87 @@ +/** + +\page exception_helper Unhandled Exception Handler + +Most Linux users are familiar with core dump. +However core dump is a tough work on Windows especially most Windows users are naive for getting core dump. +So it is essential to make an easy-to-visit core dump Feature for Windows program. +YYCC provides this feature in YYCC::ExceptionHelper. + +You may know Google also has a similar and universal project called Crashpad used by Google Chrome. +That's right. But it is too heavy. +I just want to implement a tiny but worked core dump feature on Windows. + +This module is Windows specific. +It will be invisible on other platforms. + +\section exception_helper__usage Usage + +\subsection exception_helper__usage__code Register Code + +In most scenarios, programmer only need call YYCC::ExceptionHelper::Register() when program started or module loaded. +And call YYCC::ExceptionHelper::Unregister when program exited or module unloaded. +All details are hidden by these 2 feature. +Programmer do not need worried about the implementation of unhandled exception handler. + +\subsection exception_helper__usage__location Location + +When unhandled exception occurs, +unhandled exception handler will try to record error log and core dump in following path: + +\li Error Log: \%LOCALAPPDATA\%\\CrashDumps\\program.exe.pid.log +\li Core Dump: \%LOCALAPPDATA\%\\CrashDumps\\program.exe.pid.dmp + +The italic characters program.exe and pid will be replaced by program name and process ID respectively at runtime. +Directory \%LOCALAPPDATA\%\\CrashDumps also is Windows used crash dump directory. +So you may see some other core dumps done by Windows in it. + +\subsection exception_helper__usage__last_remedy Last Remedy + +If unhandled exception handler occurs error, these stuff may not be generated correctly. +The end user may not find them and send them to you. +There is a last remedy for this scenario. + +Unhandled exception handler will still output error log in \c stderr no matter whether error log or core dump is created. +So end user always can fetch error log from console. +You only need to instruct end user open command prompt, launch application, reproduce error and get the output error log in console. +In this case, you can not get core dump. But you can get error log. +It is not good for debugging but it is better than nothing. + +Also please note the last remedy may still have a little bit possibility to occurs error and output nothing, +especially the error occurs in back trace function. +There is no guaranteen that unhandled exception handler must generate error log and core dump. + +\section exception_helper__notes Notes + +\subsection exception_helper__notes__thread_safe Thread Safe + +All exposed functions in YYCC::ExceptionHelper are thread safe. +The implementation uses \c std:mutex to ensure this. + +\subsection exception_helper__notes__singleton Singleton Handler + +YYCC::ExceptionHelper also have a mechanism that make sure the same unhandled exception handler implementation only appear once in the same process. +For example, you have an executable program A.exe, and 2 dynamic libraries B.dll and C.dll. +A.exe and B.dll use YYCC unhandled exception handler feature but C.dll not. +A.exe will load B.dll and C.dll at runtime. +Although both A.exe and B.dll call YYCC::ExceptionHelper::Register(), +when unhandled exception occurs, there is only one error report output, +which may be generated by A.exe or B.dll accoridng to their order of loading. + +The core purpose of this is making sure the program will not output too many error report for the same unhandled exception, +no matter how many modules calling YYCC::ExceptionHelper::Register() are loaded. +Only one error report is enough. + +More precisely, we use \c CreateMutexW to create an unique mutex in Windows global scope, +to make sure YYCC::ExceptionHelper::Register() only run once in the same process. +It is very like the implementation of singleton application. + +\subsection exception_helper__notes__recursive_calling Recursive Calling + +The implementation of unhandled exception handler may also will throw exception. +This will cause infinite recursive calling. +YYCC::ExceptionHelper has internal mechanism to prevent this bad case. +If this really happend, the handler will quit silent and will not cause any issue. +Programmer don't need to worry about this. + +*/ diff --git a/doc/src/index.dox b/doc/src/index.dox index 3bd8d1b..06c8813 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -50,6 +50,8 @@ \li \subpage dialog_helper + \li \subpage exception_helper +