CreateFileMappingNumaW

指定ファイルに対して名前付きまたは名前なしのファイルマッピングオブジェクトを作成または開き、物理メモリの NUMA ノードを指定する。(CreateFileMappingNumaW)

CreateFileMappingNumaW hFile, lpFileMappingAttributes, flProtect, dwMaximumSizeHigh, dwMaximumSizeLow, lpName, nndPreferred

hFile : [intptr] ファイルマッピングオブジェクトを作成する元のファイルへのハンドル。ファイルは flProtect パラメータが指定する保護フラグと互換性のあるアクセス権で開かれている必要がある。必須ではないが、マップ対象のファイルは排他アクセスで開くことが推奨される。詳細は File Security and Access Rights を参照。hFile が INVALID_HANDLE_VALUE の場合、呼び出し側プロセスは dwMaximumSizeHigh と dwMaximumSizeLow パラメータでファイルマッピングオブジェクトのサイズも指定する必要がある。この場合、CreateFileMappingNuma はファイルシステム上のファイルではなくシステムページングファイルがバックする、指定サイズのファイルマッピングオブジェクトを作成する。
lpFileMappingAttributes : [var] 返されるハンドルが子プロセスに継承可能かどうかを決定する SECURITY_ATTRIBUTES 構造体へのポインタ。SECURITY_ATTRIBUTES 構造体の lpSecurityDescriptor メンバーが新しいファイルマッピングオブジェクトのセキュリティ記述子を指定する。lpFileMappingAttributes が NULL の場合、ハンドルは継承できず、ファイルマッピングオブジェクトは既定のセキュリティ記述子を取得する。ファイルマッピングオブジェクトの既定セキュリティ記述子の ACL は作成者のプライマリトークンまたは impersonation トークンから取得される。詳細は File Mapping Security and Access Rights を参照。
flProtect : [int] ファイルマッピングオブジェクトのページ保護を指定する。このオブジェクトのすべてのマップされたビューは、この保護と互換性がなければならない。
dwMaximumSizeHigh : [int] ファイルマッピングオブジェクトの最大サイズの上位 DWORD。
dwMaximumSizeLow : [int] ファイルマッピングオブジェクトの最大サイズの下位 DWORD。このパラメータと dwMaximumSizeHigh パラメータがともに 0 の場合、ファイルマッピングオブジェクトの最大サイズは hFile パラメータが示すファイルの現在のサイズに等しい。長さ 0 のファイルをマップしようとすると、ERROR_FILE_INVALID エラーコードで失敗する。アプリケーションは長さ 0 のファイルを検査して拒否するべきである。
lpName : [wstr] ファイルマッピングオブジェクトの名前。このパラメータが既存のファイルマッピングオブジェクトの名前と一致する場合、関数は flProtect パラメータで指定された保護でオブジェクトへのアクセスを要求する。NULL の場合、名前なしでファイルマッピングオブジェクトが作成される。lpName が既存のイベント、セマフォ、ミューテックス、待機可能タイマ、またはジョブオブジェクトの名前と一致する場合、関数は失敗し GetLastError は ERROR_INVALID_HANDLE を返す。これはこれらのオブジェクトが同じ名前空間を共有するために起こる。名前にはグローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global\" または "Local\" プレフィックスを付けられる。名前の残りの部分はバックスラッシュ文字 (\\) を除く任意の文字を含められる。グローバル名前空間にファイルマッピングオブジェクトを作成するには SeCreateGlobalPrivilege 特権が必要。詳細は Kernel Object Namespaces を参照。高速ユーザー切り替えはターミナルサービスセッションを使用して実装される。最初にログオンしたユーザーがセッション 0、次にログオンしたユーザーがセッション 1、以降同様。カーネルオブジェクト名はアプリケーションが複数ユーザーをサポートできるようガイドラインに従う必要がある。
nndPreferred : [int] 物理メモリを配置する NUMA ノード。

(プラグイン / モジュール : kernel32.dll)

解説

指定ファイルに対して名前付きまたは名前なしのファイルマッピングオブジェクトを作成または開き、物理メモリの NUMA
ノードを指定する。(CreateFileMappingNumaW)

[戻り値]

関数が成功した場合、戻り値はファイルマッピングオブジェクトへのハンドル。関数呼び出し前にオブジェクトが存在していた場合、関数は既存オブジェクトへのハンドル（指定サイズではなく現在のサイズ）を返し、GetLastError
関数は ERROR_ALREADY_EXISTS を返す。関数が失敗した場合、戻り値は NULL。拡張エラー情報を取得するには
GetLastError 関数を呼ぶ。

[備考]

ファイルマッピングオブジェクトが作成された後、ファイルのサイズはファイルマッピングオブジェクトのサイズを超えてはならない。超えた場合、ファイル内容のすべてを共有できるとは限らない。ファイルマッピングオブジェクトは複製、継承、または名前によって共有できる。ページファイルがバックするファイルマッピングオブジェクト内のページの初期内容はゼロである。アプリケーションがディスク上の実際の名前付きファイルのサイズよりも大きいファイルマッピングオブジェクトのサイズを指定し、かつページ保護が書き込みアクセスを許可する場合（すなわち
flProtect パラメータが PAGE_READWRITE または PAGE_EXECUTE_READWRITE
を指定する場合）、ディスク上のファイルは指定されたファイルマッピングオブジェクトのサイズに合うよう拡張される。ファイルが拡張された場合、ファイルの古い終端と新しい終端の間の内容がゼロであることは保証されない。動作はファイルシステムによって定義される。ファイルを拡張できない場合、ファイルマッピングオブジェクトの作成に失敗し、GetLastError
関数は ERROR_DISK_FULL を返す。CreateFileMappingNuma
関数が返すハンドルは、新しいファイルマッピングオブジェクトへのフルアクセスを持ち、ファイルマッピングオブジェクトへのハンドルを必要とする任意の関数で使用できる。ファイルマッピングオブジェクトはプロセス作成、ハンドル複製、または名前で共有できる。詳細は
DuplicateHandle および OpenFileMapping
関数を参照。ファイルマッピングオブジェクトを作成してもビューをマップする可能性を作り出すだけで、ビューをマップしない。MapViewOfFileExNuma
関数がファイルのビューをプロセスアドレス空間にマップする。1
つの重要な例外を除き、単一のファイルマッピングオブジェクトから得られるファイルビューは特定の時点でコヒーレント（同一）である。複数のプロセスが同じファイルマッピングオブジェクトのハンドルを持つ場合、ファイルのビューをマップするとデータのコヒーレントなビューを得られる。例外はリモートファイルに関連する。CreateFileMappingNuma
関数はリモートファイルに対して動作するが、それらをコヒーレントに保たない。例えば、2
台のコンピュータがファイルを書き込み可能としてマップし、両方が同じページを変更した場合、それぞれのコンピュータはそのページへの自身の書き込みしか見られない。ディスク上のデータが更新されるとき、ページはマージされない。マップされたファイルと、入出力
(I/O) 関数 (ReadFile と WriteFile)
でアクセスされるファイルは必ずしもコヒーレントではない。ファイルマッピングオブジェクトを完全に閉じるには、アプリケーションは
UnmapViewOfFile 関数を呼んですべてのマップされたビューを解除し、その後 CloseHandle
関数を呼んでファイルマッピングオブジェクトのハンドルを閉じる必要がある。これらの関数は任意の順序で呼べる。UnmapViewOfFile
の呼び出しは必要である。マップされたファイルマッピングオブジェクトのビューはオブジェクトへの内部オープンハンドルを保持しており、ファイルマッピングオブジェクトはそれへのすべてのオープンハンドルが閉じられるまで閉じられない。マップされたビューを通じてファイルを変更するとき、最終更新タイムスタンプが自動的に更新されないことがある。必要ならば呼び出し側は
SetFileTime を使ってタイムスタンプを設定する。セッション 0 以外のセッションからファイルマッピングオブジェクトを作成するには
SeCreateGlobalPrivilege
特権が必要である。なお、この特権チェックはファイルマッピングオブジェクトの作成に限られ、既存のものを開くことには適用されない。例えば、サービスやシステムがファイルマッピングオブジェクトを作成した場合、呼び出し側が必要なアクセス権を持っていれば、任意のセッションで実行中の任意のプロセスがそのファイルマッピングオブジェクトにアクセスできる。メモリマップビューに書き込みや読み込みを行うコードを保護するには構造化例外処理を使う。詳細は
Reading and Writing From a File View
を参照。実行可能な権限を持つマッピングを作成するには、アプリケーションは PAGE_EXECUTE_READWRITE または
PAGE_EXECUTE_READ で CreateFileMappingNuma を呼び、その後 FILE_MAP_EXECUTE |
FILE_MAP_WRITE または FILE_MAP_EXECUTE | FILE_MAP_READ で
MapViewOfFileExNuma を呼ぶ必要がある。Windows Server 2012
では、この関数は以下の技術でサポートされている。
（以下省略）

情報