Core.h

[詳解]

/// @file
/// @brief Daemonライブラリのコア処理を提供するMonostateクラス Core のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_CORE_H
#define AMDAEMON_CORE_H

#include "amdaemon/env.h"
#include "amdaemon/deprecated.h"
#include "amdaemon/NextProcess.h"
#include "amdaemon/RequestState.h"

#include <functional>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_core
/// @{

    // 前方宣言
    class Exception;

    /// @brief Daemonライブラリのコア処理を提供するMonostateクラス。
    ///
    /// @par ライブラリ利用アプリで実装すべきこと
    /// - メンバ関数 #execute を毎フレーム呼び出し、状態を更新すること。
    /// - 下記タイミングではメンバ関数 #isReady が true を返すまで待機すること。
    ///     - Daemonプロセス起動時。
    ///     - Sequence クラスによってゲームテストモードを開始した時。
    ///     - Sequence クラスによってゲームテストモードを終了した時。
    /// - 上記タイミングの際、並行してアプリ固有の初期化処理を行っても構わないが、
    ///   Core クラスおよび Error クラスの一部関数を除き、
    ///   @ref g_common "主要クラス" は利用しないこと。
    ///     - 特に、メンバ関数 #kill 以外の処理要求関数を呼び出した場合は例外が発生する。
    /// - アプリを終了してセガブートやシステムテストモードへ移行する場合は
    ///   メンバ関数 #kill を呼び出すこと。(詳細は後述)
    ///
    /// @par アプリ終了フロー
    /// - アプリを終了させてセガブートやシステムテストモードへ遷移する場合、
    ///   まずメンバ関数 #kill を呼び出してDaemonプロセスを終了させ、
    ///   その後速やかにアプリを終了させること。
    /// - メンバ関数 #kill を呼び出さずにアプリを終了させてしまうとセガブートにて
    ///   ERROR 10 が表示される。
    ///     - アプリが異常終了した場合にもこの挙動となる。
    /// - セガブートやシステムテストモードへ遷移するわけではなく、続けて別のアプリを
    ///   起動させる場合は、メンバ関数 #kill を呼び出してはならない。
    /// - NET配信やLANインストールによるセガブート遷移要求ではなく、
    ///   アプリ都合での再起動が目的である場合、メンバ関数 #kill ではなくメンバ関数
    ///   #reboot を用いてハードウェアリセットすること。
    ///     - メンバ関数 #kill によってセガブート経由でアプリを再起動させた場合、
    ///       以降電断もしくはハードウェアリセットが行われるまでの間、
    ///       NET配信によるセガブート遷移要求が行われなくなる。
    ///       即ち、解禁済みのパッチイメージが存在する場合であっても、
    ///       NetDelivery クラスのメンバ関数 NetDelivery#isExitNeeded が true を返さなくなる。
    ///
    /// @par アプリの強制終了における注意事項
    /// メンバ関数 #execute や各種ブロッキング処理の実行中にアプリを強制終了させた場合、
    /// 内部で用いているプロセス間排他ロック機構が有効なままとなる場合がある。
    /// 主に、デバッガから終了させた場合等が該当する。
    /// @par
    /// その状態で、Daemonプロセスやエミュレータを終了させずに再度アプリを起動すると、
    /// メンバ関数 #execute を呼び出した時点でデッドロックが発生する。
    /// この状態に陥った場合、Daemonプロセスやエミュレータを一旦終了させること。
    /// @par
    /// 実運用においては、アプリを強制終了させるようなフローを組み込まないようにすること。
    /// また、前述のアプリ終了フローに従うこと。
    ///
    /// @ingroup g_common
    class Core
    {
    public:
        // 下記は暗黙の定義を用いる。
        //Core() = default;
        //‾Core() = default;
        //Core(const Core&) = default;
        //Core& operator=(const Core&) = default;

        /// @brief ライブラリバージョンを表す文字列を取得する。
        /// @return ライブラリバージョンを表す文字列。
        ///
        /// amdaemon.lib のバージョンを表す libver 形式の文字列を返す。
        /// ただし前後の改行は除く。
        ///
        /// 例えば "amdaemonLib Ver.1987 Build:Apr  5 2017 10:01:23" といった文字列になる。
        ///
        /// アプリのデバッグ表示やログ出力にそのまま用いることを想定している。
        const wchar_t* getLibraryVersion() const;

        /// @brief Daemonライブラリの更新処理を行う。
        ///
        /// アプリのメインループ処理内で毎フレーム呼び出すこと。
        void execute();

        /// @brief Daemonプロセスの主要な初期化が完了したか否かを取得する。
        /// @retval true  初期化完了している場合。
        /// @retval false 初期化未完了であるが、Daemonプロセスが起動していない場合。
        ///
        /// 下記のタイミングにおいて、この関数が true を返すまで待機すること。
        ///
        /// - Daemonプロセス起動時。
        /// - Sequence クラスによってゲームテストモードを開始した時。
        /// - Sequence クラスによってゲームテストモードを終了した時。
        ///
        /// ただしDaemonプロセスが生存していない場合、この関数は true を返さず、
        /// メンバ関数 #isExited が true を返す。
        ///
        /// @attention
        /// この関数が true を返すまで、 Core クラスおよび Error クラスの一部関数を除き、
        /// @ref g_common "主要クラス" を利用してはならない。
        ///
        /// @attention
        /// この関数が返す値の更新はメンバ関数 #execute によって行われるため、
        /// この関数が返す値に関わらずメンバ関数 #execute は毎フレーム呼び出すこと。
        bool isReady() const;

        /// @brief Daemonプロセスを終了させる。
        /// @param[in] nextProcess アプリ終了後の遷移先。既定値は NextProcess::Auto 。
        /// @see #reboot
        /// @note
        ///     Core#isReady が false を返す状態でも利用可能。
        ///     ただしブロッキング時間は長くなる。
        ///
        /// この関数を呼び出した後は速やかにアプリを終了させること。
        /// Core クラスのアプリ終了フローに関する説明も参照すること。
        ///
        /// アプリ都合での再起動を行いたい場合、この関数ではなくメンバ関数
        /// #reboot によるハードウェアリセットを行うこと。
        ///
        /// Daemonプロセス起動直後など、
        /// Daemonプロセスの準備が完了していないタイミングで呼び出した場合、
        /// 最長で20秒程度ブロッキングする場合がある。
        ///
        /// エミュレータ環境で呼び出した場合、エミュレータが終了するのみである。
        void kill(NextProcess nextProcess = NextProcess::Auto);

        /// @brief [非推奨] Daemonプロセスを終了させる。
        /// @param[in] errorOnSegaBoot
        ///     現在 Error クラスにエラーが設定されている場合に、
        ///     そのエラーをセガブートで表示させるように設定するならば true 。
        /// @note
        ///     Core#isReady が false を返す状態でも利用可能。
        ///     ただしブロッキング時間は長くなる。
        /// @deprecated kill(NextProcess) オーバロードを利用すること。
        ///
        /// 現在 Error クラスにエラーが設定されており、
        /// かつ引数 errorOnSegaBoot に true を指定した場合、
        /// kill(NextProcess) オーバロードの引数に
        /// NextProcess::SegaBootError を指定した場合と同一の挙動となる。
        ///
        /// 上記の条件を満たさない場合、 kill(NextProcess) オーバロードの引数に
        /// NextProcess::Auto を指定した場合と同一の挙動となる。
        AMDAEMON_DEPRECATED("Replace to `kill(NextProcess)`.")
        void kill(bool errorOnSegaBoot);

        /// @brief Daemonプロセスが終了済みであるか否かを取得する。
        /// @retval true  終了済みである場合。
        /// @retval false 実行中である場合。
        /// @note メンバ関数 #isReady が false を返す状態でも利用可能。
        ///
        /// 次のいずれかの場合に終了済み扱いとなる。
        ///
        /// - メンバ関数 #kill を呼び出して終了させた場合。
        /// - Daemonプロセスの生存が一定時間確認できず、落ちていると判断された場合。
        ///
        /// 後者の場合、 Error クラスにエラーが設定される。
        bool isExited() const;

        /// @brief プレイヤー数を取得する。
        /// @return プレイヤー数。
        /// @see Player
        ///
        /// Daemonプロセスの設定ファイルで指定した仮想プレイヤー数が返る。
        std::size_t getPlayerCount() const;

        /// @brief 例外をスローする代わりに呼び出される例外フック関数を設定する。
        /// @param[in] hook フック関数。
        /// @note メンバ関数 #isReady が false を返す状態でも利用可能。
        /// @see resetExceptionHook, Exception
        ///
        /// この関数でフック関数(コールバック)を設定すると、以降ライブラリ内部で例外が
        /// 発生した時、それをスローするのではなくフック関数に渡すようになる。
        ///
        /// フック関数内で明示的にスローしない限り、例外発生元からもスローされない。
        /// スローされなくなった場合の挙動は例外カテゴリに依存する。
        /// 詳細は各 @ref ExceptionCategory 列挙値の説明を参照すること。
        ///
        /// フック関数には、第1引数に Exception オブジェクト参照を受け取る関数もしくは
        /// 関数オブジェクトを指定できる。
        /// 任意のクラスのメンバ関数を指定したい場合はラムダ式を用いるとよい。
        ///
        /// @code
        /// // 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); });
        /// }
        /// @endcode
        void setExceptionHook(std::function<void (const Exception&)> hook);

        /// @brief 例外フック関数を解除し、例外がスローされるようにする。
        /// @note メンバ関数 #isReady が false を返す状態でも利用可能。
        /// @see setExceptionHook
        void resetExceptionHook();

        /// @brief 現在設定されている言語名を取得する。
        /// @return 言語名。
        const wchar_t* getLanguage() const;

        /// @brief 言語名の設定と関連リソースのロードを要求する。
        /// @param[in] language 言語名。設定ファイルの内容を適用するならば nullptr 。
        /// @retval true  処理に成功した場合。
        /// @retval false 処理に失敗した場合。
        ///
        /// @exception Exception
        /// 引数 language の文字数が 0 文字または 16 文字以上である場合。
        ///
        /// 関連リソースのロードに1箇所でも失敗した場合は処理に失敗する。
        /// その場合、言語名は変更されない。
        ///
        /// 引数 language に nullptr を渡した場合に選択される言語名は
        /// Daemonプロセスの設定ファイルでの指定に準ずる。
        /// Daemonプロセスの初期化時にも自動で選択されるため、
        /// 既定の言語をそのまま用いるのであればこの関数を呼び出す必要はない。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        /// リソースのロードに数秒掛かる可能性があるため、頻繁に呼び出さないこと。
        bool changeLanguage(const wchar_t* language);

        /// @brief ハードウェアリセットを行う。
        /// @see kill(NextProcess)
        ///
        /// ハードウェアリセットを行う。Windowsの再起動とは異なるので注意。
        ///
        /// 処理に成功した場合、この関数からは復帰しない。
        ///
        /// 下記の場合はこの関数から復帰する。
        ///
        /// - 処理に失敗した場合。
        /// - エミュレータ環境で呼び出した場合。
        ///
        /// 処理失敗の主な原因としてはDaemonプロセスが異常終了した場合等が考えられるが、
        /// 基本的には Error クラスによりエラーが通知されているはずである。
        ///
        /// NET配信やLANインストールによるセガブート遷移要求に対応する場合は、
        /// この関数ではなくメンバ関数 #kill を用いること。
        /// 詳しくは Core クラスのアプリ終了フローに関する説明を参照すること。
        void reboot();

        /// @brief アプリおよび依存DLLの .data セクションを事前ロードする。
        /// @return 要求状態値。処理中や事前ロード済みの場合は無効値。
        ///
        /// このライブラリをリンクしているアプリ、およびそれが依存しているDLLの
        /// .data セクションを事前ロードする。
        ///
        /// @par .data セクションの事前ロードとは
        /// 実行可能ファイル(*.exe)やDLLは、 .data セクションと呼ばれるバイナリ領域に
        /// グローバル変数や静的ローカル変数を格納しており、
        /// プログラム内で初めて利用されるタイミングでそのロード処理が行われる。
        /// @par
        /// グローバル変数等を大量に用いているアプリの場合、
        /// ロード処理によりプログラムの動作が一瞬固まることが確認されている。
        /// @par
        /// この関数を用いて .data セクションを事前ロードすることにより、
        /// 上記の問題を解消できる。
        ///
        /// この関数の呼び出し自体は即座に完了し、要求状態値を返す。
        /// RequestState クラスの各メンバ関数により、
        /// Daemonプロセスが処理完了済みか否かや処理の成否等を調べることができる。
        ///
        /// ただし、下記のいずれかを満たす場合、この関数は無効な要求状態値を返す。
        ///
        /// - 既にこの関数による事前ロード処理中である場合。
        /// - 既にこの関数による事前ロード処理が成功済みである場合。
        ///
        /// 無効な要求状態値が返ってきた場合、要求は発行されていない。
        /// 有効であるか否かは
        /// RequestState クラスのメンバ関数 RequestState#valid で判別できる。
        ///
        /// この関数の処理中はDaemonプロセスがブロッキングされるため、
        /// 同時に別のAM関連処理を行うことはできない。
        /// また、アプリのフレームレートが安定しない可能性がある。
        ///
        /// 上記の理由から、アプリの初期化シーケンスにおいてメンバ関数 #isReady が
        /// true を返すようになった直後にこの関数を呼び出し、
        /// 処理完了までアプリでは簡易的な画面表示に留めることが望ましい。
        ///
        /// エミュレータ環境で呼び出した場合、処理は成功となるが、内部的には何も行われない。
        RequestState preloadDataSection();
    };

/// @}
} // amdaemon

//--------------------
// Doxygen用コメント
//--------------------

/**
@mainpage AM Daemon ライブラリリファレンス

@par AM Daemon とは
Aime、ALL.Net等、AMゲーム開発で共通して利用されるモジュール群をパッケージングし、
ゲームアプリからより簡潔に扱えるようにすることを目的とするプロセス＆ライブラリ。

@par AM Daemon ライブラリとは
AM Daemon プロセスにゲームアプリからアクセスして、
情報を取得したり処理を要求したりするためのインタフェースライブラリ。@n
AM Daemon プロセスは当ライブラリを通してアクセスされることを前提とした設計になっており、
AM Daemon 採用タイトルのゲームアプリは必ず当ライブラリを組み込む必要がある。

@par 主要クラス
当ライブラリの @ref g_common "主要クラス" はいずれも
@ref amdaemon 名前空間に属し、Monostateクラスとなっている。@n
ライブラリ利用アプリは好きな場所でインスタンスを作成して利用することができる。@n
少なくとも amdaemon::Core クラスのメンバ関数
@ref amdaemon::Core::execute "execute"
は必ず毎フレーム呼び出す必要がある。

@par 例外処理
ライブラリ内で例外が発生した場合、既定では
amdaemon::Exception クラスのインスタンスがスローされる。
@par
この動作が好ましくない場合、 amdaemon::Core クラスのメンバ関数
@ref amdaemon::Core::setExceptionHook "setExceptionHook"
を用いて例外フック関数を設定すること。@n
例外フック関数が設定されている場合、例外をスローする代わりに例外フック関数が呼び出される。@n
詳しくは amdaemon::Core::setExceptionHook 関数の説明を参照すること。

@par ライブラリで用いる文字列について
当ライブラリにおいて文字列を引数、戻り値等で用いる場合、その値は const wchar_t* 型あるいは
std::wstring 型のワイド文字列となる。@n
アプリ側もこれに合わせてワイド文字列ベースで実装を行うことを推奨する。@n
Visual C++ 環境においてワイド文字列ベースの実装を行うには、プロジェクトのプロパティから
「構成プロパティ→全般→文字セット」の値を「Unicode 文字セットを使用する」に変更すること。
@par
他ライブラリの都合等により const char* 型や
std::string 型の文字列値を当ライブラリとやり取りする必要がある場合、
amdaemon::util::WinEncoding クラスを利用すると手軽に文字コード変換を行える。@n
詳しくは amdaemon::util::WinEncoding クラスの説明を参照すること。
*/

/**
@defgroup g_common common : 主要クラス
@brief AM Daemon ライブラリ主要クラス一覧。

@defgroup g_util util : ユーティリティ
@brief AM Daemon プロセスとは無関係だが便利なクラス、関数等の定義。

@defgroup g_exception exception : 例外処理
@brief AM Daemon の例外処理関連定義。

@defgroup g_dump dump : 共有メモリダンプ
@brief 共有メモリ情報のダンプ処理関連定義。

@defgroup g_core Core : コア処理
@brief Daemonライブラリのコア処理を提供するMonostateクラス Core とその関連定義。

@defgroup g_abaas abaas : ABaaS
@brief ABaaS(ALL.Net Backend as a Service)関連処理を提供するMonostateクラス abaas::Log とその関連定義。

@defgroup g_aime Aime : Aime
@brief Aime関連処理を提供するMonostateクラス Aime とその関連定義。

@defgroup g_allnet allnet : ALL.Net
@brief ALL.Net関連処理を提供するMonostateクラス allnet::Auth, allnet::Accounting とその関連定義。

@defgroup g_appimage AppImage : アプリイメージ情報
@brief アプリイメージ関連情報を提供するMonostateクラス AppImage とその関連定義。

@defgroup g_backup Backup : 不揮発データバックアップ
@brief 不揮発データバックアップ処理を提供するMonostateクラス Backup とその関連定義。

@defgroup g_boardio BoardIO : ボード入出力
@brief 【Nuシリーズ用】DipSwitch、PushSwitch、LEDの情報を提供するMonostateクラス BoardIO とその関連定義。
@attention Nuシリーズでのみ利用可能。

@defgroup g_can Can : CAN通信
@brief 【Nuシリーズ用】CAN通信処理を提供するMonostateクラス Can とその関連定義。
@attention Nuシリーズでのみ利用可能。

@defgroup g_credit Credit : クレジット
@brief ビデオゲームのクレジット処理を提供するMonostateクラス Credit とその関連定義。

@defgroup g_emoney EMoney : 電子マネー
@brief 【ALLSシリーズ用】電子マネー処理を提供するMonostateクラス EMoney とその関連定義。
@attention ALLSシリーズの電子マネー対応版SDKでのみ利用可能。

@defgroup g_error Error : エラー
@brief Daemonが検出したエラーの情報を提供するMonostateクラス Error とその関連定義。

@defgroup g_io I/O : 抽象入出力
@brief ID付けされた入出力情報を提供するMonostateクラス Input, Output とその関連定義。

@defgroup g_jvs Jvs : JVS入出力
@brief 【Nuシリーズ用】JVSの入出力処理を提供するMonostateクラス Jvs とその関連定義。
@attention Nuシリーズでのみ利用可能。

@defgroup g_laninstall LanInstall : LANインストール
@brief LANインストール情報を提供するMonostateクラス LanInstall とその関連定義。

@defgroup g_netdelivery NetDelivery : NET配信
@brief NET配信情報を提供するMonostateクラス NetDelivery とその関連定義。

@defgroup g_network Network : ネットワーク
@brief ネットワーク関連処理を提供するMonostateクラス Network とその関連定義。

@defgroup g_player Player : プレイヤー
@brief プレイヤーに紐付く情報をまとめて提供するMonostateクラス Player とその関連定義。

@defgroup g_sequence Sequence : ゲームシーケンス
@brief ゲームシーケンスを管理するMonostateクラス Sequence とその関連定義。

@defgroup g_system System : システム情報
@brief システムの不変情報を提供するMonostateクラス System とその関連定義。

@defgroup g_usbdevice UsbDevice : USBデバイス
@brief USBデバイス関連処理を提供するMonostateクラス UsbDevice とその関連定義。

@defgroup g_usbio UsbIO : USB入出力
@brief USBの入出力処理を提供するMonostateクラス UsbIO とその関連定義。
*/

/**
@namespace amdaemon
@brief AM Daemon ライブラリクラス群の基底名前空間。

@namespace amdaemon::allnet
@brief ALL.Net関連のクラス等を定義する名前空間。
@ingroup g_allnet

@namespace amdaemon::abaas
@brief ABaaS(ALL.Net Backend as a Service)関連のクラス等を定義する名前空間。
@ingroup g_abaas

@namespace amdaemon::util
@brief AM Daemon プロセスとは無関係だが便利なクラス、関数等を定義する名前空間。
@ingroup g_util
*/

#endif // AMDAEMON_CORE_H