amdaemon::Core クラス

Daemonライブラリのコア処理を提供するMonostateクラス。 [詳解]

#include <Core.h>

公開メンバ関数
const wchar_t *	getLibraryVersion () const
	ライブラリバージョンを表す文字列を取得する。 [詳解]
void	execute ()
	Daemonライブラリの更新処理を行う。 [詳解]
bool	isReady () const
	Daemonプロセスの主要な初期化が完了したか否かを取得する。 [詳解]
void	kill (NextProcess nextProcess=NextProcess::Auto)
	Daemonプロセスを終了させる。 [詳解]
void	kill (bool errorOnSegaBoot)
	[非推奨] Daemonプロセスを終了させる。 [詳解]
bool	isExited () const
	Daemonプロセスが終了済みであるか否かを取得する。 [詳解]
std::size_t	getPlayerCount () const
	プレイヤー数を取得する。 [詳解]
void	setExceptionHook (std::function< void(const Exception &)> hook)
	例外をスローする代わりに呼び出される例外フック関数を設定する。 [詳解]
void	resetExceptionHook ()
	例外フック関数を解除し、例外がスローされるようにする。 [詳解]
const wchar_t *	getLanguage () const
	現在設定されている言語名を取得する。 [詳解]
bool	changeLanguage (const wchar_t *language)
	言語名の設定と関連リソースのロードを要求する。 [詳解]
void	reboot ()
	ハードウェアリセットを行う。 [詳解]
RequestState	preloadDataSection ()
	アプリおよび依存DLLの .data セクションを事前ロードする。 [詳解]

詳解

Daemonライブラリのコア処理を提供するMonostateクラス。

ライブラリ利用アプリで実装すべきこと

• メンバ関数 execute を毎フレーム呼び出し、状態を更新すること。
• 下記タイミングではメンバ関数 isReady が true を返すまで待機すること。
  • Daemonプロセス起動時。
  • Sequence クラスによってゲームテストモードを開始した時。
  • Sequence クラスによってゲームテストモードを終了した時。
• 上記タイミングの際、並行してアプリ固有の初期化処理を行っても構わないが、 Core クラスおよび Error クラスの一部関数を除き、 主要クラス は利用しないこと。
  • 特に、メンバ関数 kill 以外の処理要求関数を呼び出した場合は例外が発生する。
• アプリを終了してセガブートやシステムテストモードへ移行する場合は メンバ関数 kill を呼び出すこと。(詳細は後述)

アプリ終了フロー

• アプリを終了させてセガブートやシステムテストモードへ遷移する場合、 まずメンバ関数 kill を呼び出してDaemonプロセスを終了させ、 その後速やかにアプリを終了させること。
• メンバ関数 kill を呼び出さずにアプリを終了させてしまうとセガブートにて ERROR 10 が表示される。
  • アプリが異常終了した場合にもこの挙動となる。
• セガブートやシステムテストモードへ遷移するわけではなく、続けて別のアプリを 起動させる場合は、メンバ関数 kill を呼び出してはならない。
• NET配信やLANインストールによるセガブート遷移要求ではなく、 アプリ都合での再起動が目的である場合、メンバ関数 kill ではなくメンバ関数 reboot を用いてハードウェアリセットすること。
  • メンバ関数 kill によってセガブート経由でアプリを再起動させた場合、 以降電断もしくはハードウェアリセットが行われるまでの間、 NET配信によるセガブート遷移要求が行われなくなる。 即ち、解禁済みのパッチイメージが存在する場合であっても、 NetDelivery クラスのメンバ関数 NetDelivery::isExitNeeded が true を返さなくなる。

アプリの強制終了における注意事項

メンバ関数 execute や各種ブロッキング処理の実行中にアプリを強制終了させた場合、 内部で用いているプロセス間排他ロック機構が有効なままとなる場合がある。 主に、デバッガから終了させた場合等が該当する。

その状態で、Daemonプロセスやエミュレータを終了させずに再度アプリを起動すると、 メンバ関数 execute を呼び出した時点でデッドロックが発生する。 この状態に陥った場合、Daemonプロセスやエミュレータを一旦終了させること。

実運用においては、アプリを強制終了させるようなフローを組み込まないようにすること。 また、前述のアプリ終了フローに従うこと。

関数詳解

const wchar_t* amdaemon::Core::getLibraryVersion

(

)

const

ライブラリバージョンを表す文字列を取得する。

戻り値

ライブラリバージョンを表す文字列。

amdaemon.lib のバージョンを表す libver 形式の文字列を返す。 ただし前後の改行は除く。

例えば "amdaemonLib Ver.1987 Build:Apr 5 2017 10:01:23" といった文字列になる。

アプリのデバッグ表示やログ出力にそのまま用いることを想定している。

void amdaemon::Core::execute

(

)

Daemonライブラリの更新処理を行う。

アプリのメインループ処理内で毎フレーム呼び出すこと。

bool amdaemon::Core::isReady

(

)

const

Daemonプロセスの主要な初期化が完了したか否かを取得する。

戻り値

true	初期化完了している場合。
false	初期化未完了であるが、Daemonプロセスが起動していない場合。

下記のタイミングにおいて、この関数が true を返すまで待機すること。

• Daemonプロセス起動時。
• Sequence クラスによってゲームテストモードを開始した時。
• Sequence クラスによってゲームテストモードを終了した時。

ただしDaemonプロセスが生存していない場合、この関数は true を返さず、 メンバ関数 isExited が true を返す。

注意

この関数が true を返すまで、 Core クラスおよび Error クラスの一部関数を除き、 主要クラス を利用してはならない。

この関数が返す値の更新はメンバ関数 execute によって行われるため、 この関数が返す値に関わらずメンバ関数 execute は毎フレーム呼び出すこと。

void amdaemon::Core::kill

(

NextProcess

nextProcess = NextProcess::Auto

)

Daemonプロセスを終了させる。

引数

[in]

nextProcess

アプリ終了後の遷移先。既定値は NextProcess::Auto 。

参照

reboot

覚え書き

Core::isReady が false を返す状態でも利用可能。 ただしブロッキング時間は長くなる。

この関数を呼び出した後は速やかにアプリを終了させること。 Core クラスのアプリ終了フローに関する説明も参照すること。

アプリ都合での再起動を行いたい場合、この関数ではなくメンバ関数 reboot によるハードウェアリセットを行うこと。

Daemonプロセス起動直後など、 Daemonプロセスの準備が完了していないタイミングで呼び出した場合、 最長で20秒程度ブロッキングする場合がある。

エミュレータ環境で呼び出した場合、エミュレータが終了するのみである。

void amdaemon::Core::kill

(

bool

errorOnSegaBoot

)

[非推奨] Daemonプロセスを終了させる。

引数

[in]

errorOnSegaBoot

現在 Error クラスにエラーが設定されている場合に、 そのエラーをセガブートで表示させるように設定するならば true 。

覚え書き

Core::isReady が false を返す状態でも利用可能。 ただしブロッキング時間は長くなる。

非推奨:

kill(NextProcess) オーバロードを利用すること。

現在 Error クラスにエラーが設定されており、 かつ引数 errorOnSegaBoot に true を指定した場合、 kill(NextProcess) オーバロードの引数に NextProcess::SegaBootError を指定した場合と同一の挙動となる。

上記の条件を満たさない場合、 kill(NextProcess) オーバロードの引数に NextProcess::Auto を指定した場合と同一の挙動となる。

bool amdaemon::Core::isExited

(

)

const

Daemonプロセスが終了済みであるか否かを取得する。

戻り値

true	終了済みである場合。
false	実行中である場合。

覚え書き

メンバ関数 isReady が false を返す状態でも利用可能。

次のいずれかの場合に終了済み扱いとなる。

• メンバ関数 kill を呼び出して終了させた場合。
• Daemonプロセスの生存が一定時間確認できず、落ちていると判断された場合。

後者の場合、 Error クラスにエラーが設定される。

std::size_t amdaemon::Core::getPlayerCount

(

)

const

プレイヤー数を取得する。

戻り値

プレイヤー数。

参照

Player

Daemonプロセスの設定ファイルで指定した仮想プレイヤー数が返る。

void amdaemon::Core::setExceptionHook

(

std::function< void(const Exception &)>

hook

)

例外をスローする代わりに呼び出される例外フック関数を設定する。

引数

[in]

hook

フック関数。

覚え書き

メンバ関数 isReady が false を返す状態でも利用可能。

参照

resetExceptionHook, Exception

この関数でフック関数(コールバック)を設定すると、以降ライブラリ内部で例外が 発生した時、それをスローするのではなくフック関数に渡すようになる。

フック関数内で明示的にスローしない限り、例外発生元からもスローされない。 スローされなくなった場合の挙動は例外カテゴリに依存する。 詳細は各 ExceptionCategory 列挙値の説明を参照すること。

フック関数には、第1引数に Exception オブジェクト参照を受け取る関数もしくは 関数オブジェクトを指定できる。 任意のクラスのメンバ関数を指定したい場合はラムダ式を用いるとよい。

// MyClass クラスのメンバ関数 doHook を指定する例
void setHook(MyClass& c)
{
    amdaemon::Core core;
    core.setExceptionHook(
        [&c](const amdaemon::Exception& e) { c.doHook(e); });
}

// MyClass クラスのメンバ関数内から指定する例
void MyClass::setHook()
{
    amdaemon::Core core;
    core.setExceptionHook(
        [this](const amdaemon::Exception& e) { doHook(e); });
}

void amdaemon::Core::resetExceptionHook

(

)

例外フック関数を解除し、例外がスローされるようにする。

覚え書き

メンバ関数 isReady が false を返す状態でも利用可能。

参照

setExceptionHook

const wchar_t* amdaemon::Core::getLanguage

(

)

const

現在設定されている言語名を取得する。

戻り値

言語名。

bool amdaemon::Core::changeLanguage

(

const wchar_t *

language

)

言語名の設定と関連リソースのロードを要求する。

引数

[in]

language

言語名。設定ファイルの内容を適用するならば nullptr 。

戻り値

true	処理に成功した場合。
false	処理に失敗した場合。

例外

Exception

引数 language の文字数が 0 文字または 16 文字以上である場合。

関連リソースのロードに1箇所でも失敗した場合は処理に失敗する。 その場合、言語名は変更されない。

引数 language に nullptr を渡した場合に選択される言語名は Daemonプロセスの設定ファイルでの指定に準ずる。 Daemonプロセスの初期化時にも自動で選択されるため、 既定の言語をそのまま用いるのであればこの関数を呼び出す必要はない。

Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。 リソースのロードに数秒掛かる可能性があるため、頻繁に呼び出さないこと。

void amdaemon::Core::reboot

(

)

ハードウェアリセットを行う。

参照

kill(NextProcess)

ハードウェアリセットを行う。Windowsの再起動とは異なるので注意。

処理に成功した場合、この関数からは復帰しない。

下記の場合はこの関数から復帰する。

• 処理に失敗した場合。
• エミュレータ環境で呼び出した場合。

処理失敗の主な原因としてはDaemonプロセスが異常終了した場合等が考えられるが、 基本的には Error クラスによりエラーが通知されているはずである。

NET配信やLANインストールによるセガブート遷移要求に対応する場合は、 この関数ではなくメンバ関数 kill を用いること。 詳しくは Core クラスのアプリ終了フローに関する説明を参照すること。

RequestState amdaemon::Core::preloadDataSection

(

)

アプリおよび依存DLLの .data セクションを事前ロードする。

戻り値

要求状態値。処理中や事前ロード済みの場合は無効値。

このライブラリをリンクしているアプリ、およびそれが依存しているDLLの .data セクションを事前ロードする。

.data セクションの事前ロードとは

実行可能ファイル(*.exe)やDLLは、 .data セクションと呼ばれるバイナリ領域に グローバル変数や静的ローカル変数を格納しており、 プログラム内で初めて利用されるタイミングでそのロード処理が行われる。

グローバル変数等を大量に用いているアプリの場合、 ロード処理によりプログラムの動作が一瞬固まることが確認されている。

この関数を用いて .data セクションを事前ロードすることにより、 上記の問題を解消できる。

この関数の呼び出し自体は即座に完了し、要求状態値を返す。 RequestState クラスの各メンバ関数により、 Daemonプロセスが処理完了済みか否かや処理の成否等を調べることができる。

ただし、下記のいずれかを満たす場合、この関数は無効な要求状態値を返す。

• 既にこの関数による事前ロード処理中である場合。
• 既にこの関数による事前ロード処理が成功済みである場合。

無効な要求状態値が返ってきた場合、要求は発行されていない。 有効であるか否かは RequestState クラスのメンバ関数 RequestState::valid で判別できる。

この関数の処理中はDaemonプロセスがブロッキングされるため、 同時に別のAM関連処理を行うことはできない。 また、アプリのフレームレートが安定しない可能性がある。

上記の理由から、アプリの初期化シーケンスにおいてメンバ関数 isReady が true を返すようになった直後にこの関数を呼び出し、 処理完了までアプリでは簡易的な画面表示に留めることが望ましい。

エミュレータ環境で呼び出した場合、処理は成功となるが、内部的には何も行われない。

---

このクラス詳解は次のファイルから抽出されました:

• Core.h