Theolizer  Version.1.2.0
serializer for C++ / Do you want to update your classes easily ?
7h.error_report.h
[詳解]
1 //############################################################################
2 /*!
3  @brief ドキュメント・ファイル－使用方法（個別）
4  @ingroup Documents
5  @file 7h.error_report.h
6  @author Yoshinori Tahara
7  @date 2017/05/03 Created
8 */
9 /*
10  © 2016 Theoride Technology (http://theolizer.com/) All Rights Reserved.
11  "Theolizer" is a registered trademark of Theoride Technology.
12 
13  "Theolizer" License
14  In the case where you are in possession of a valid “Theolizer” License,
15  you may use this file in accordance with the terms and conditions of
16  the use license determined by Theoride Technology.
17 
18  General Public License Version 3 ("GPLv3")
19  You may use this file in accordance with the terms and conditions of
20  GPLv3 published by Free Software Foundation.
21  Please confirm the contents of GPLv3 at https://www.gnu.org/licenses/gpl.txt .
22  A copy of GPLv3 is also saved in a LICENSE.TXT file.
23 
24  商用ライセンス
25  あなたが有効なTheolizer商用ライセンスを保持している場合、
26  セオライド テクノロジーの定める使用許諾書の条件に従って、
27  このファイルを取り扱うことができます。
28 
29  General Public License Version 3(以下GPLv3)
30  Free Software Foundationが公表するGPLv3の使用条件に従って、
31  あなたはこのファイルを取り扱うことができます。
32  GPLv3の内容を https://www.gnu.org/licenses/gpl.txt にて確認して下さい。
33  またGPLv3のコピーをLICENSE.TXTファイルにおいてます。
34 */
35 //############################################################################
36 
37 
38 /*!
39  @page ErrorReport エラー報告
40 ここではTheolizerが検出するエラーの受け取り方とその後処理について説明します。
41 
42 <br>
43 //############################################################################
44 @section ErrorReport1 1.Theolizerエラー・クラス
45 //############################################################################
46 
47 @subsection ErrorInfo 1-1.ErrorInfoクラス
48 Theolzierのエラーは report.h で定義している theolizer::ErrorInfo クラスで表現します。<br>
49 主な公開メンバは以下の通りです。<br>
50 
51 |メンバ名|意味|
52 |--------|----|
53 |theolizer::ErrorType getErrorType() const;|エラー種別コード返却|
54 |theolizer::ErrorKind getErrorKind() const;|エラー分類コード返却|
55 |std::string getString() const;|全エラー情報を含むエラー・メッセージ返却|
56 |bool isError() const;|エラーならtrue|
57 |operator bool() const;|エラーか警告ならtrue|
58 |bool operator!() const;|エラーも警告もないならtrue|
59 
60 
61 @subsection ErrorType 1-2.ErrorType枚挙型
62 <b>theolizer::ErrorType</b>はenum型で以下のシンボルを持ちます。
63 |シンボル名|意味|
64 |----------|----|
65 |None|エラーでも警告でも無い|
66 |Warning|警告|
67 |Error|エラー|
68 
69 @subsection ErrorKind 1-3.ErrorKind枚挙型
70 <b>theolizer::ErrorKind</b>はenum型で以下のシンボルを持ちます。
71 |シンボル名|意味|
72 |----------|----|
73 |Unclassified|未分類|
74 |WrongUsing|使い方間違い|
75 |IOError|I/O動作エラー|
76 |UnknownData|非対応シリアライズ・データ・フォーマット|
77 |UnknownVerson|非対応バージョン（未知のグローバル・バージョン番号）|
78 
79 @subsection getString 1-4.ErrorInfoのgetString()のフォーマット
80 ErrorInfoのgetString()で取得できる文字列は次のようなフォーマットです。<br>
81 @code
82 ErrorType(ErrorKind),エラーを検出したインスタンス{ソース・ファイル名(行番号)} : エラー・メッセージ
83 @endcode
84 エラーを検出したインスタンス直後の"{ソース・ファイル名(行番号)}"は可能な時のみ表示されます。
85 
86 <b>シリアライザのコンストラクタでエラー検出した時（型チェック・エラー）の例</b><br>
87 @code
88 Error(UnknownData),IntrusiveBase2.mULongLong : Unmatch type.{core_serializer.cpp(1570)}
89 @endcode
90 なお、このエラー・メッセージに含まれるソース・ファイルと行番号は、当該エラーを検出したTheolizerのソースと行番号です。
91 
92 <b>THEOLIZER_PROCESS()等のマクロ内でエラー検出した時の例</b><br>
93 @code
94 Error(UnknownData),aInt{test_basic_process.cpp(212)} : Logical Error on stream.
95 @endcode
96 
97 <br>
98 //############################################################################
99 @section ErrorReport2 2.Theolizerで検出したエラーの記録
100 //############################################################################
101 
102 Theolizerは２種類のエラー記録を持っています。
103 どちらとも複数回エラーか警告が発生した場合、最後のエラーが記録されます。<br>
104 ただし、エラー記録を優先するため、エラー発生後の警告はエラーが解除(resetError)されるまで記録されません。
105 
106 @subsection SerializerInstance 2-1.シリアライザのインスタンス
107 シリアライザ・インスタンス毎に当該シリアライザで発生したエラー（もしくは警告）を保持します。<br>
108 警告ではないエラーが発生している場合、シリアライザへの要求は全て処理されず、WrongUsingとなります。<br>
109 回復するためには、ストリームの再同期とresetError()呼び出しが必要です。<br>
110 <br>
111 エラー情報に関するメンバ関数は「@ref MemberFunctions 」を参照下さい。<br>
112 
113 @subsection ErrorReporter 2-2.ErrorReporterシングルトン
114 theolizer::ErrorReporterはthread_localなシングルトンですのでスレッド毎に一つだけ存在します。<br>
115 当該スレッドで発生した最後のエラーか警告を保持します。<br>
116 シングルトンですのでコンストラクト、コピー、ムーブできません。<br>
117 <br>
118 以下のstatic関数が公開されています。<br>
119 
120 |メンバ名|意味|
121 |--------|----|
122 |static theolizer::ErrorInfo const& getErrorInfo() noexcept;|エラー情報を返却します。|
123 |static bool isError() noexcept;|エラーが発生している時trueを返却します。|
124 |static void resetError() noexcept;|エラー状態を解除します。|
125 
126 <br>
127 //############################################################################
128 @section ErrorReport3 3.Theolizerで検出したエラーの通知方法
129 //############################################################################
130 
131 シリアライザからのエラー通知方法は２つあります。
132 
133 1. 例外許可の場合<br>
134 シリアライザ・コンストラクタのiNoThrowExceptionパラメータをfalse（デフォルト）として、シリアライザをコンストラクトすると例外が許可されます。<br>
135 エラーを検出した時に theolizer::ErrorInfo 例外を throw します。<br>
136 <br>
137 2. 例外禁止の場合<br>
138 シリアライザ・コンストラクタのiNoThrowExceptionパラメータをtrueにして、シリアライザをコンストラクトすると例外が禁止されます。<br>
139 エラーを検出しても例外を投げません。getErrorInfo()等でエラー情報を受け取って下さい。<br>
140 
141 <div style="padding: 10px; margin-bottom: 10px; border: 1px solid #333333; border-radius: 10px; background-color: #d0d0d0;">
142 <b>シリアライザにエラー状態が残ったままデストラクトしないで下さい</b><br>
143 エラーの受け取り忘れを防止するため、エラーが発生しているのにresetError()せずにデストラクトするとプログラムを強制終了させていますので、例外を禁止している時は、必ずエラーを受け取りresetError()してからデストラクトするようにして下さい。（@ref ErrorReport6 参照）<br>
144 <br>
145 なお、例外許可時はエラーの受け取り損ないは発生しないためresetError()してなくても強制終了しません。
146 </div>
147 
148 <br>
149 //############################################################################
150 @section ErrorReport4 4.エラー状態の回復方法
151 //############################################################################
152 
153 シリアライザのエラー状態を解除するには、下記の手順で行います。<br>
154 
155 1. シリアライザへ渡しているストリームを同期する。<br>
156 次に読むべきデータ先頭から読み出せる状態にします。<br>
157 この処理はユーザ・プログラムにて行って下さい。<br>
158 <br>
159 2. シリアライザのエラーをリセットする。<br>
160 シリアライザ・インスタンス.resetError()により行います。<br>
161 <br>
162 
163 ただし、一般にファイルからの回復時にエラーが発生した時の原因は下記ですので、ファイルへの保存／回復の場合はストリームをオープンしたままエラー回復する操作を行うことは原則としてありません。<br>
164 
165 - プログラムのバグ（Theolizerが非対応な変更をしたプログラムで回復しようとした。）
166 - ファイル指定ミス（指定したフォーマットと実際のフォーマットの不一致）
167 - ファイル破壊
168 
169 通信による受信時にエラーが発生した時は、再同期することでリカバリすることが可能です。<br>
170 なお、通信回線の同期はTheolizerによるサポートはありません。ユーザ・プログラムにて再同期して下さい。<br>
171 <br>
172 
173 <br>
174 //############################################################################
175 @section ErrorReport5 5.エラー・ログ
176 //############################################################################
177 
178 TheolizerはTheolizerで検出したエラーをログ・ファイルへ記録する機能をサポートしています。<br>
179 
180 @subsection THEOLIZER_ERRORLOG_FILE 5-1.THEOLIZER_ERRORLOG_FILE()マクロの指定方法
181 
182 THEOLIZER_ERRORLOG_FILE()マクロをユーザ・プログラム内で１箇所だけ書くことで有効になります。<br>
183 
184 グローバル名前空間で以下を記述します。
185 @code
186 THEOLIZER_ERRORLOG_FILE("LogFilePath%1%.log");
187 @endcode
188 
189 - "LogFilePath"の部分でエラー・ログのパスを指定します。<br>
190 相対パスで指定した場合、プログラム起動時のカレント・フォルダからの相対になります。<br>
191 <br>
192 - "%1%"はTheolizerがログ・ファイルの番号として使います。<br>
193 ログ・ファイル番号は0開始です。<br>
194 ログ・ファイルはデフォルトでは1MBytesを超えると次のログ・ファイルへ切り替わります。その時、ログ・ファイル番号をインクリメントします。<br>
195 ただし、デフォルトでは最大2個までに制限していますので、ログ・ファイル番号1の次は0のログ・ファイルへ「上書き」します。<br>
196 これにより、ほっておいてもログ・ファイルが無限に増えることを防止しています。<br>
197 <br>
198 - ".log"は自由に指定して下さい。<br>
199 <br>
200 
201 @subsection LogFileFormat 5-2.ログ・ファイルのフォーマット
202 
203 ログ・ファイルは後処理するのに便利のため簡易的なcsvフォーマットにしています。以下の通りです。<br>
204 
205 - 先頭行<br>
206 シーケンシャル番号です。これはログ・ファイルを生成する度に1つ増えます。<br>
207 unsigned型で循環します。<br>
208 <br>
209 - ２行目以降<br>
210 @code
211 ,年-月-日,時間:分:秒.mSec,同期待ち時間(uSec),スレッドID,ErrorType(ErrorKind),エラー検出インスタンス : エラー・メッセージ
212 @endcode
213 
214 <b>ログ・ファイル例：</b><br>
215 @code
216 0
217 ,2017-05-04,13:32:38.671,000001,___________12712,Error(UnknownData),IntrusiveBase2.mULongLong : Unmatch type.{core_serializer.cpp(1570)}
218 ,2017-05-04,13:32:38.673,000000,___________12712,Error(UnknownData),IntrusiveBase2.mULongLong : Unmatch type.{core_serializer.cpp(1570)}
219 ,2017-05-04,13:32:38.673,000000,___________12712,Error(WrongUsing),mIntrusiveBase2{test_serializer_base02.cpp(91)} : Unmatch type.
220 ,2017-05-04,13:32:38.673,000000,___________12712,Error(UnknownData),IntrusiveBase2.mULongLong : Unmatch type.{core_serializer.cpp(1654)}
221 ,2017-05-04,13:32:38.674,000000,___________12712,Error(UnknownData),IntrusiveBase2.mULongLong : Unmatch type.{core_serializer.cpp(1654)}
222 ,2017-05-04,13:32:38.674,000000,___________12712,Error(WrongUsing),mIntrusiveBase2{test_serializer_base02.cpp(123)} : Unmatch type.
223 @endcode
224 
225 @subsection WaitSync 5-3.同期待ち時間について
226 エラー・ログ出力は、マルチ・スレッドに対応しています。<br>
227 他のスレッドがエラー・ログ出力処理中に出力しようとした場合、後から出力する方は待たされます。<br>
228 その待ち時間を uSec で記録します。<br>
229 <br>
230 
231 @subsection ThreadId 5-4.スレッドIDについて
232 当該ログを出力したスレッドIDを`std::this_thread::get_id()`で獲得して記録します。<br>
233 
234 <br>
235 //############################################################################
236 @section ErrorReport6 6.サンプル・ソース
237 //############################################################################
238 
239 <b>サンプル・ソース（source/reference_and_test/basic/test_basic_process.cpp）</b><br>
240 @snippet basic/test_basic_process.cpp ErrorReport
241 
242 これの出力は以下のようになります。
243 
244 @code
245 exception : Error(UnknownData),aInt{test_basic_process.cpp(241)} : Logical Error on stream.
246 no-exception : Error(UnknownData),ashort{test_basic_process.cpp(256)} : Logical Error on stream.
247 @endcode
248 
249 <br>
250 //############################################################################
251 @section ErrorReport7 7.エラー検出の網羅的テスト
252 //############################################################################
253 
254 @subsection ErrorReport71 7-1.エラー報告全体
255 テスト用のソース・コードは、source/test_library/reportフォルダに置いています。<br>
256 下記の組合せでテストしています。
257 
258 |ソース・ファイル|テスト内容|
259 |----------------|----------|
260 |test_report1.cpp |エラー・ログが適切に保存されること<br>エラー・ログ・ファイルの指定ミス<br>マルチ・スレッドに対応できていること |
261 |test_report1_child.cpp |エラー・ログ・ファイル指定ミスのテスト用の子プロセス |
262 |test_report2.cpp |THEOLIZER_ERRORLOG_FILE未指定 |
263 |test_report3.cpp<br>test_report4.cpp |THEOLIZER_ERRORLOG_FILE多重登録 |
264 |test_report4.cpp |ErrorReproterのAPIテスト |
265 
266 @subsection ErrorReport72 7-2.downVersion/upVersionのコンパイル・エラー
267 プリミティブ型とenum型以外のメンバ変数への値設定が禁止できていることをテストしています。
268 
269 ソース・コードは、source/reference_and_test/ver3b/test_modify_complex.hにて、ERROR1, ERROR2マクロが定義されている時にコンパイル・エラーになるように定義しています。そして、source/reference_and_test/CMakeLists.txtのver3bERROR1, ver3bERROR2にてコンパイル・エラーが発生することをチェックしています。
270 
271 @subsection ErrorReport73 7-3.グローバル・バージョン番号テーブルのエラー検出
272 バージョン・アップに伴い、一度シリアライズ指定したクラスやenum型をソース・コードから完全に削除した場合に、グローバル・バージョン番号テーブルから手動で削除する必要があります。（@ref Basic344 参照。）<br>
273 その削除を忘れた場合にコンパイル・エラーになることを確認しています。
274 
275 ソース・コードは、source/reference_and_test/ver3b/test_modify_complex.hにて、ERROR3マクロが定義されている時にコンパイル・エラーになるように定義しています。そして、source/reference_and_test/CMakeLists.txtのver3bERROR3にてコンパイル・エラーが発生することをチェックしています。
276 
277 @subsection ErrorReport74 7-4.エラー・リカバリ
278 デシリアライズ中のエラー発生後にリカバリするテストを行っています。
279 Json, BinaryシリアライザのNoTypCheck, TypeCheck, TypeCheckByIndexについて、現バージョンと１つ前のバージョンからの回復についてリカバリできることを確認しています。
280 
281 ソース・コードは、source/reference_and_test/ver2a/test_modify_complex.cppのtutoriseModifyComplex()関数です。
282 
283 
284 */