非同期処理の管理クラスのルートクラスです。 [詳解]
#include <OnlineCore/src/Core/CallContext.h>
公開型 | |
typedef void(* | CompletionCallback) (CallContext *, const UserContext *) |
CompletionCallback を定義します。 [詳解] | |
enum | Flags { , DeleteOnCompletion = 0x02, OneWayCall = 0x04, SendUnreliableMessage = 0x08 } |
CallContext に使用可能な各種フラグを列挙します。 [詳解] | |
enum | State { Available, CallInProgress, CallSuccess, CallFailure, CallCancelled } |
CallContext の状態を列挙します。 [詳解] | |
公開メンバ関数 | |
CallContext () | |
コンストラクタです。 | |
virtual | ~CallContext () |
デストラクタです。 [詳解] | |
RefCountedObject * | AcquireRef () |
参照カウントを 1 増加させます。 | |
qBool | Cancel () |
この CallContext に関連付けられている非同期処理をキャンセルします。 [詳解] | |
void | ClearFlag (qUnsignedInt32 uiFlag) |
SetFlag を使用して設定されたフラグをクリアします。 [詳解] | |
qBool | FlagIsSet (qUnsignedInt32 uiFlag) const |
特定のフラグが設定されているかどうかを返します。 [詳解] | |
virtual qBool | FlagsAreValid () const |
現在使用されているフラグの組み合わせが有効かどうかを返します。 [詳解] | |
qResult | GetOutcome () const |
非同期処理の結果を qResult として取得します。 [詳解] | |
State | GetState () const |
CallContext の現在の状態を返します。 [詳解] | |
const UserContext & | GetUserContext (size_t iIndex) const |
この CallContext に関連付けられている UserContext を返します。 [詳解] | |
void | RegisterCompletionCallback (CompletionCallback pfCompletionCallback, const UserContext &oContext, qBool bAddToEnd=true) |
この CallContext の完了時に実行するコールバック関数を設定します。 [詳解] | |
void | RegisterCompletionCallback (CallbackRoot *pCallback, qBool bCallOnSuccess=true, qBool bAddToEnd=true) |
この CallContext の完了時に実行するコールバックオブジェクトを設定します。 [詳解] | |
template<typename TCallback > | |
void | RegisterCompletionCallbackGeneric (const TCallback &callback, qBool deleteCallbackAfterCall=false, qBool bAddToEnd=true) |
この CallContext の完了時に実行するコールバックを設定します。 [詳解] | |
void | ReleaseRef () |
参照カウントを 1 減少させます。0 になるときに自分自身を delete します。 | |
qBool | Reset () |
CallContext の状態を利用可能に再設定します。 [詳解] | |
void | SetFlag (qUnsignedInt32 uiFlag) |
非同期処理に使用するフラグを設定します。 [詳解] | |
void | SetTimeout (TimeInterval tiTimeout) |
非同期処理のタイムアウトをセットします。 [詳解] | |
void | SetUserContext (size_t iIndex, const UserContext &oUserContext) |
この CallContext に関連付けられている UserContext を設定します。 [詳解] | |
void | Trace (qUnsignedInt64 uiTraceFlags=TRACE_ALWAYS) |
この CallContext オブジェクトの内容をトレースします。 リリースモードで実行されると自動的に無効になります。 [詳解] | |
qBool | Wait (qUnsignedInt32 uiTimeout=WAIT_INFINITE_TIMEOUT) |
非同期処理が完了する、またはタイムアウトを越えるまで内部処理を進め、待機します。 [詳解] | |
qBool | WaitWithoutDispatch (qUnsignedInt32 uiTimeout=WAIT_INFINITE_TIMEOUT) |
非同期処理が完了する、またはタイムアウトを越えるまで待機します。 [詳解] | |
非同期処理の管理クラスのルートクラスです。
NEX でサーバーとの通信などで非同期処理を実行するには、非同期関数の引数に、 CallContext クラスやそのサブクラス (サーバーとの通信が発生する場合は ProtocolCallContext クラス)を渡します。 CallContext クラスを利用することで、 非同期処理の状態や結果に関する情報の取得や、キャンセルやリセット、タイムアウトの設定などもできます。
typedef void(* nn::nex::CallContext::CompletionCallback) (CallContext *, const UserContext *) |
CompletionCallback を定義します。
処理完了時に特定のユーザー定義関数が呼び出されるように、CompletionCallback を RegisterCompletionCallback() で登録します。
CallContext の状態を列挙します。
非同期処理を開始すると Available から CallInProgress に遷移し、処理が終了すると CallSuccess、CallFailure、CallCancelled のいずれかの完了状態に遷移します。
列挙値 | |
---|---|
Available |
実行可能。 |
CallInProgress |
処理を実行中。この状態のときは他の非同期処理の Context としては使用できません。 |
CallSuccess |
処理が成功して終了しました。 |
CallFailure |
処理が失敗して終了しました。 |
CallCancelled |
処理がキャンセルされました。 |
CallContext に使用可能な各種フラグを列挙します。
列挙値 | |
---|---|
DeleteOnCompletion |
処理が完了したタイミングで ReleaseRef() が呼ばれます。 |
OneWayCall |
呼び出しが一方通行になります。この呼び出しに対する結果は返されません。 このフラグはRMCContext のためだけに用意されています。もしも相手先のメソッドが値を返したとき、 値は無視されて返答されません。しかし、常に、メッセージが相手に対して送信されたのかどうかは ブール値として返ります。もしもこのフラグがセットされていたら、この呼び出しは複数の対象を取ることができ、 SendUnreliableMessage, CallOnDuplicas, CallOnMaster, CallOnNeighbouringStations, CallOnLocalStationの 各フラグと一緒に設定しても問題ありません。 |
SendUnreliableMessage |
呼び出しはアンリライアブル(到達保証性のない)チャンネルを利用します。 このフラグはRMCContext のために用意されています。 また、OneWayCallフラグも同時にセットされていなければなりません。 |
|
virtual |
デストラクタです。
状態が CallInProgress である場合、関連付けられた非同期処理はキャンセルされます。
DeleteOnCompletionフラグが設定された場合、この CallContext を使用する非同期処理の完了時にデストラクタが自動的に呼び出されます。
void nn::nex::CallContext::SetTimeout | ( | TimeInterval | tiTimeout | ) |
非同期処理のタイムアウトをセットします。
非同期処理の開始後 tiTimeout ミリ秒後に非同期処理が完了していない( CallInProgress )場合に、 自動的に状態が CallFailure に移行し、 GetOutcome() で取得できる qResult が QRESULT(Core, Timemout) になります。
[in] | tiTimeout | タイムアウト時間(ミリ秒) |
State nn::nex::CallContext::GetState | ( | ) | const |
CallContext の現在の状態を返します。
NEX のスレッドモードがスレッドアンセーフモードであっても、本関数は Scheduler::Dispatch() を含む任意の他の関数と同時に呼び出すことができます。
void nn::nex::CallContext::SetUserContext | ( | size_t | iIndex, |
const UserContext & | oUserContext | ||
) |
この CallContext に関連付けられている UserContext を設定します。
[in] | iIndex | この CallContext に関連付けられている UserContext のユーザー定義インデックスです。 |
[in] | oUserContext | この CallContext に関連付けされている UserContext へのポインタ。 |
const UserContext& nn::nex::CallContext::GetUserContext | ( | size_t | iIndex | ) | const |
この CallContext に関連付けられている UserContext を返します。
[in] | iIndex | 返される UserContext のユーザー定義インデックスです。 |
void nn::nex::CallContext::SetFlag | ( | qUnsignedInt32 | uiFlag | ) |
|
virtual |
現在使用されているフラグの組み合わせが有効かどうかを返します。
nn::nex::DOCallContextで再実装されています。
void nn::nex::CallContext::ClearFlag | ( | qUnsignedInt32 | uiFlag | ) |
qBool nn::nex::CallContext::FlagIsSet | ( | qUnsignedInt32 | uiFlag | ) | const |
void nn::nex::CallContext::RegisterCompletionCallback | ( | CompletionCallback | pfCompletionCallback, |
const UserContext & | oContext, | ||
qBool | bAddToEnd = true |
||
) |
この CallContext の完了時に実行するコールバック関数を設定します。
設定したコールバックはこの CallContext が完了状態に遷移したときに呼び出されます。 このコールバックを使用することで、 CallContext が完了したかどうかを確認するためにポーリングする手間を省くことができます。
本関数を複数回呼び出すことで複数のコールバックを登録することが出来ます。 複数のコールバックを登録した場合はデフォルトでは登録順にコールバックの呼び出しが行われ、最初に登録されたコールバックは最初に呼び出されます。 この順序を変更したい場合は、コールバックを登録する際に bAddToEnd パラメータを設定する必要があります。
コールバック関数内では NEX のブロック関数を呼び出さないようにしてください。
[in] | pfCompletionCallback | 完了時に呼び出されるコールバック関数へのポインタ。 |
[in] | oContext | 呼び出されるコールバック関数へ渡される UserContext 。 |
[in] | bAddToEnd | true(デフォルト)であれば、コールバックはリストの最後に追加されます。falseであればリストの先頭に追加されます。 |
void nn::nex::CallContext::RegisterCompletionCallback | ( | CallbackRoot * | pCallback, |
qBool | bCallOnSuccess = true , |
||
qBool | bAddToEnd = true |
||
) |
この CallContext の完了時に実行するコールバックオブジェクトを設定します。
設定したコールバックはこの CallContext が完了状態に遷移したときに呼び出されます。 このコールバックを使用することで、 CallContext が完了したかどうかを確認するためにポーリングする手間を省くことができます。
本関数を複数回呼び出すことで複数のコールバックを登録することが出来ます。 複数のコールバックを登録した場合はデフォルトでは登録順にコールバックの呼び出しが行われ、最初に登録されたコールバックは最初に呼び出されます。 この順序を変更したい場合は、コールバックを登録する際に bAddToEnd パラメータを設定する必要があります。
コールバック関数内では NEX のブロック関数を呼び出さないようにしてください。
[in] | pCallback | 完了時に呼び出されるコールバックオブジェクトへのポインタ。 |
[in] | bCallOnSuccess | 真(デフォルト)であれば、 コールバックは非同期処理の成功時にのみ呼び出されます。 |
[in] | bAddToEnd | true(デフォルト)であれば、コールバックはリストの最後に追加されます。falseであればリストの先頭に追加されます。 |
qBool nn::nex::CallContext::Reset | ( | ) |
CallContext の状態を利用可能に再設定します。
このメソッドは、 State が Sucess 、 Failure または Cancelled のいずれかひとつである場合のみ、呼び出すことができます。
State が CallInProgress のときに本関数が呼び出されると、エラー SYSTEMERROR_GEN_INVALID_OPERATION になります。 State が Available の場合、本関数は true を返しますが、何も起こりません。
qBool nn::nex::CallContext::Wait | ( | qUnsignedInt32 | uiTimeout = WAIT_INFINITE_TIMEOUT | ) |
非同期処理が完了する、またはタイムアウトを越えるまで内部処理を進め、待機します。
本関数は、 CallContext の State が CallInProgress の場合に呼び出すことができます。 非同期処理が完了する、またはタイムアウトを越えるまで本関数の内部で Scheduler::Dispatch() が呼び出されます。
タイムアウトを越えた場合は、エラー SYSTEMERROR_GEN_TIMEOUT が発生します。 タイムアウトを越えた場合でも非同期処理が継続するため、非同期処理のout引数は解放できません。 out引数を解放したい場合は明示的に CallContext::Cancel() を呼び出してください。
[in] | uiTimeout | 待機する最大の時間(ミリ秒)。デフォルトのuiTimeoutは無限大です。 |
qBool nn::nex::CallContext::WaitWithoutDispatch | ( | qUnsignedInt32 | uiTimeout = WAIT_INFINITE_TIMEOUT | ) |
非同期処理が完了する、またはタイムアウトを越えるまで待機します。
本関数は、 CallContext の State が CallInProgress の場合に呼び出すことができます。 非同期処理が完了する、またはタイムアウトを越えるまで処理を戻しません。 CallContext::Wait() とは異なり、本関数内部で Scheduler::Dispatch() は呼び出されません。 内部処理を進めるには他のスレッドで Scheduler::Dispatch() などを呼び出す必要があります。 NEX のスレッドモードがスレッドアンセーフモードであっても、 本関数は Scheduler::Dispatch() を含む任意の他の関数と同時に呼び出すことができます。
タイムアウトを越えた場合でも非同期処理が継続するため、非同期処理のout引数は解放できません。 out引数を解放したい場合は明示的に CallContext::Cancel() を呼び出してください。
[in] | uiTimeout | 待機する最大の時間(ミリ秒)。デフォルトのuiTimeoutは無限大です。 |
qBool nn::nex::CallContext::Cancel | ( | ) |
この CallContext に関連付けられている非同期処理をキャンセルします。
CallContext に関連付けされた非同期処理のうち、まだ実行されていない処理を放棄します。 本関数から戻った後は非同期処理開始時にセットした out 引数を解放する事ができます。
すでに実行されている処理については取り消す事は出来ず、どこまで処理されたかを知る方法はありません。 例えば、サーバーに対して何らかのリクエストを行う処理をキャンセルした場合、サーバーへのリクエストを送信した後に キャンセルが行われてもそのリクエストはサーバーで処理されます。その結果を呼び出し側で受信してもそれを無視するという動作になります。
主に非同期処理の結果を無視して良い状況で非同期処理開始時にセットしたout引数を解放する目的で使用してください。
本関数で非同期処理がキャンセルされた場合、返値は true となり非同期処理の結果は QERROR(Core, Cancelled) になります。 ステートが CallInProgress 以外だった場合にキャンセルした場合は返値は false となり、キャンセル処理は行われません。
true 非同期処理がキャンセルされた。(ステートが CallInProgress だった場合)
false 非同期処理が開始されていないものをキャンセルしようとした。(ステートが Available だった場合。) もしくはすでに非同期処理が完了していた。(ステートが CallSuccess もしくは CallFailure もしくは CallCancelled だった場合。)
qResult nn::nex::CallContext::GetOutcome | ( | ) | const |
非同期処理の結果を qResult として取得します。
特定の非同期処理に対する結果を取得します。 結果の内容については CallContext をパラメータとしてとる関数を参照してください。
void nn::nex::CallContext::Trace | ( | qUnsignedInt64 | uiTraceFlags = TRACE_ALWAYS | ) |
この CallContext オブジェクトの内容をトレースします。 リリースモードで実行されると自動的に無効になります。
[in] | uiTraceFlags | TraceLog::SetFlag() の引数と同様です。 |
void nn::nex::CallContext::RegisterCompletionCallbackGeneric | ( | const TCallback & | callback, |
qBool | deleteCallbackAfterCall = false , |
||
qBool | bAddToEnd = true |
||
) |
この CallContext の完了時に実行するコールバックを設定します。
設定したコールバックはこの CallContext が完了状態に遷移したときに呼び出されます。 このコールバックを使用することで、 CallContext が完了したかどうかを確認するためにポーリングする手間を省くことができます。
callback には CallContext* を引数に取る関数ポインタ、関数オブジェクト、ラムダ式を指定できます。 AddCallContextArgumentAdapter() を併用すると引数を一つも取らない関数を渡すこともできます。
関数オブジェクトを渡す場合は値もしくは参照型で渡す方法とポインタ型で渡す方法の二種類があり、それぞれ挙動が異なります。 値もしくは参照型で渡した場合は内部で関数オブジェクトがコピーもしくはムーブされ、コールバックはそのコピーもしくはムーブされたオブジェクトに対して行われます。 そのため、本関数呼び出し後は指定したオブジェクトを即座に破棄する事ができます。 ポインタ型で渡した場合は、コールバックはそのポインタが指すオブジェクトに対して行われます。 そのため、コールバックが呼び出されるまでその関数オブジェクトを呼び出し側で保持しておく必要があります。
本関数を複数回呼び出すことで複数のコールバックを登録することが出来ます。 複数のコールバックを登録した場合はデフォルトでは登録順にコールバックの呼び出しが行われ、最初に登録されたコールバックは最初に呼び出されます。 この順序を変更したい場合は、コールバックを登録する際に bAddToEnd パラメータを設定する必要があります。
callback に関数オブジェクトをポインタで渡した場合は deleteCallbackAfterCall を true にする事で callback の呼び出し後に自動的に callback を delete することができます。 もし callback を delete するのではなくアプリケーション独自の解放処理を行いたい場合は、 再度本関数を呼び出しそのための関数オブジェクトを追加する事で実装が可能です。
コールバック関数内では NEX のブロック関数を呼び出さないようにしてください。
[in] | callback | コールバックする関数ポインタもしくは関数オブジェクトもしくはラムダ式。 |
[in] | deleteCallbackAfterCall | callback の実行が完了した後自動的に callback を delete するかどうか。 |
[in] | bAddToEnd | true(デフォルト)であれば、コールバックはリストの最後に追加されます。falseであればリストの先頭に追加されます。 |