非同期コールバック処理
クライアントがプロバイダーの仮想化ルートの下にあるファイルとディレクトリを操作すると、通常、これらの相互作用によってプロバイダーのコールバックが呼び出されます。 ProjFS は、カーネル モードから ProjFS ユーザー モード ライブラリにメッセージを送信することによってプロバイダー コールバックを呼び出します。ここで、ワーカー スレッドはメッセージを受信し、適切なコールバックを呼び出します。 コールバックが返されると、ワーカー スレッドはカーネル モードから別のメッセージが到着するまで待機します。 すべてのワーカー スレッドがプロバイダー コールバック コードの実行中にビジー状態の場合、コールバックをトリガーするそれ以上のクライアント I/O は、ワーカー スレッドがメッセージを受信して関連するコールバックを呼び出すまでブロックします。 プロバイダーが起動すると、PrjStartVirtualizing の options パラメーターを使用して、ProjFS がサービス コールバックに対して作成するワーカー スレッドの数を指定できます。 プロバイダーは、コールバックを非同期的に処理することで、メッセージ受信ワーカー スレッドの効率を向上させることができます。
プロバイダーが options パラメーターを PrjStartVirtualizing に指定しない場合、または options パラメーターの ConcurrentThreadCount メンバーに 0 を指定した場合、ProjFS は ConcurrentThreadCount の値にシステム内の論理プロセッサの数を使用します。
プロバイダーが options パラメーターを PrjStartVirtualizing に指定しない場合、または options パラメーターの PoolThreadCount メンバーに 0 を指定した場合、ProjFS は PoolThreadCount の値に ConcurrentThreadCount の値の 2 倍を使用します。
プロバイダー サービスコールバックは、コールバックからHRESULT_FROM_WIN32(ERROR_IO_PENDING) を返し、後で PrjCompleteCommand を使用してそれらを完了することによって非同期的にコールバックします。 コールバックを非同期的に処理するプロバイダーは、 PRJ_CANCEL_COMMAND_CB コールバックを実装することで、コールバックの取り消しもサポートする必要があります。
ProjFS は、プロバイダーのコールバックを呼び出すときに、コールバックの callbackData パラメーターの CommandId メンバーを使用して、コールバックの特定の呼び出しを識別します。 プロバイダーがそのコールバックを非同期的に処理することを決定した場合は、CommandId メンバーの値を格納し、コールバックから HRESULT_FROM_WIN32(ERROR_IO_PENDING) を返す必要があります。 プロバイダーはコールバックの処理を完了すると、 PrjCompleteCommand を呼び出し、格納されている識別子を commandId パラメーターに渡します。 これにより、どのコールバック呼び出しが完了したかが ProjFS に通知されます。
PRJ_CANCEL_COMMAND_CB コールバックを実装するプロバイダーは、まだ完了していないコールバックを追跡する必要があります。 プロバイダーがこのコールバックを受け取った場合、これらのコールバックの 1 つを呼び出す原因となった I/O が、明示的に取り消されたか、または終了時に発行されたスレッドによって取り消されたことを示します。 プロバイダーは、CommandId によって識別されたコールバック呼び出しの処理をできるだけ早く取り消す必要があります。
ProjFS は、取り消されるコールバックが呼び出された後にのみ、指定された CommandId の PRJ_CANCEL_COMMAND_CB を呼び出しますが、キャンセルと元の呼び出しは、マルチスレッド プロバイダーで同時に実行できます。 プロバイダーは、この状況を適切に処理できる必要があります。
次のサンプルは、「 ファイルとディレクトリの列挙 」トピックに指定されたサンプルのバージョンであり、非同期コールバック処理を示すように変更されています。
typedef struct MY_ENUM_ENTRY MY_ENUM_ENTRY;
typedef struct MY_ENUM_ENTRY {
MY_ENUM_ENTRY* Next;
PWSTR Name;
BOOLEAN IsDirectory;
INT64 FileSize;
} MY_ENUM_ENTRY;
typedef struct MY_ENUM_SESSION {
GUID EnumerationId;
PWSTR SearchExpression;
USHORT SearchExpressionMaxLen;
BOOLEAN SearchExpressionCaptured;
MY_ENUM_ENTRY* EnumHead;
MY_ENUM_ENTRY* LastEnumEntry;
BOOLEAN EnumCompleted;
} MY_ENUM_SESSION;
typedef struct MY_ENUM_PARAMS {
GUID EnumerationId;
PRJ_DIR_ENTRY_BUFFER_HANDLE DirEntryBufferHandle;
PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT NamespaceVirtualizationContext;
INT32 CommandId;
PRJ_CALLBACK_DATA_FLAGS Flags;
WCHAR SearchExpression[1];
} MY_ENUM_PARAMS;
// Prototype for the enumeration worker routine. In this example this is a
// ThreadProc. See https://msdn.microsoft.com/library/windows/desktop/ms686736.aspx
DWORD WINAPI MyGetEnumCallbackWorker(_In_ LPVOID parameter);
#define ROLLBACK_NONE 0
#define ROLLBACK_PARAM_ALLOC 1
#define ROLLBACK_TRACK_ENUM 2
HRESULT
MyGetEnumCallback(
_In_ const PRJ_CALLBACK_DATA* callbackData,
_In_ const GUID* enumerationId,
_In_opt_z_ PCWSTR searchExpression,
_In_ PRJ_DIR_ENTRY_BUFFER_HANDLE dirEntryBufferHandle
)
{
UINT rollback = ROLLBACK_NONE;
// This example creates a thread to run the enumeration in. The provider
// can access callbackData only while the callback is running, so we copy
// out the fields that the worker thread will need.
MY_ENUM_PARAMS* enumParams = NULL;
size_t bufSize = sizeof(MY_ENUM_PARAMS);
// Allocate enough space for the parameter buffer and the search expression
// string plus a terminating NULL character.
if (searchExpression != NULL)
{
bufSize += (wcslen(searchExpression) + 1) * sizeof(WCHAR);
}
else
{
// We'll store "*" as the search expression in this case.
bufSize += 2 * sizeof(WCHAR);
}
enumParams = (MY_ENUM_PARAMS*) calloc(1, bufSize);
if (enumParams == NULL)
{
hr = E_OUTOFMEMORY;
goto RollbackOnError;
}
// enumParams allocated.
rollback = ROLLBACK_PARAM_ALLOC;
// Copy the search expression into our parameter buffer.
if (searchExpression != NULL)
{
wcsncpy_s(enumParams->SearchExpression,
wcslen(searchExpression),
searchExpression,
wcslen(searchExpression));
}
else
{
wcsncpy_s(enumParams->SearchExpression, 1, "*", 1);
}
// Copy the other parameters into our parameter buffer.
enumParams->EnumerationId = enumerationId;
enumParams->DirEntryBufferHandle = dirEntryBufferHandle;
enumParams->NamespaceVirtualizationContext = callbackData->NamespaceVirtualizationContext
enumParams->CommandId = callbackData->CommandId;
enumParams->Flags = callbackData->Flags;
// MyTrackEnumForCancellation is a routine the provider might implement to
// track active enumeration callbacks in case they are cancelled. It stores
// the CommandId for the callback in some structure.
hr = MyTrackEnumForCancellation(callbackData->CommandId);
if (FAILED(hr))
{
goto RollbackOnError;
}
// Enum callback tracked.
rollback = ROLLBACK_TRACK_ENUM;
// Create the worker thread.
HANDLE workerThread = NULL;
workerThread = CreateThread(NULL,
0,
MyGetEnumCallbackWorker,
enumParams,
0
NULL);
// We'll treat failure to create the thread as a low-resources error.
if (workerThread == NULL)
{
hr = E_OUTOFMEMORY;
goto RollbackOnError;
}
// Return pending to signal that we'll complete the enumeration later.
return HRESULT_FROM_WIN32(ERROR_IO_PENDING);
RollbackOnError:
// Clean up manually. Note the fall-through structure of the switch, and that
// we clean up in reverse order.
switch(rollback)
{
case ROLLBACK_TRACK_ENUM:
// MyUntrackEnumForCancellation removes the CommandId for the callback
// from the structure that MyTrackEnumForCancellation put it in.
MyUntrackEnumForCancellation(callbackData->CommandId);
case ROLLBACK_PARAM_ALLOC:
free(enumParams);
default:
break;
}
return hr;
}
DWORD
WINAPI
MyGetEnumCallbackWorker(
_In_ LPVOID parameter
)
{
HRESULT hr = S_OK;
MY_ENUM_PARAMS* enumParams = (MY_ENUM_PARAMS*) parameter;
// MyCheckEnumForCancellation is a routine the provider might implement to
// check whether a pended enumeration callback has been cancelled. Even
// though the enumeration has been cancelled, ProjFS will still call the
// provider's end-enumeration callback. This allows general cleanup, such
// as tearing down the enumeration session, to always happen in that callback.
if (MyCheckEnumForCancellation(enumParams->CommandId))
{
// The operation has been cancelled. Clean up and get out.
free(enumParams);
return 0;
}
// MyGetEnumSession is a routine the provider might implement to find
// information about the enumeration session that it first stored
// when processing its PRJ_START_DIRECTORY_ENUMERATION_CB callback.
//
// In this example the PRJ_START_DIRECTORY_ENUMERATION_CB callback has
// already retrieved a list of the items in the backing store located at
// callbackData->FilePathName, sorted them using PrjFileNameCompare()
// to determine collation order, and stored the list in session->EnumHead.
MY_ENUM_SESSION* session = NULL;
session = MyGetEnumSession(enumParams->EnumerationId);
if (session == NULL)
{
hr = HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER);
goto CompleteCallback;
}
if (!session->SearchExpressionCaptured ||
(enumParams->Flags & PRJ_CB_DATA_FLAG_ENUM_RESTART_SCAN))
{
if (wcsncpy_s(session->SearchExpression,
session->SearchExpressionMaxLen,
enumParams->SearchExpression,
wcslen(enumParams->SearchExpression)))
{
// Failed to copy the search expression; perhaps the provider
// could try reallocating session->SearchExpression.
}
session->SearchExpressionCaptured = TRUE;
}
MY_ENUM_ENTRY* enumHead = NULL;
// We have to start the enumeration from the beginning if we aren't
// continuing an existing session or if the caller is requesting a restart.
if (((session->LastEnumEntry == NULL) &&
!session->EnumCompleted) ||
(enumParams->Flags & PRJ_CB_DATA_FLAG_ENUM_RESTART_SCAN))
{
// Ensure that if the caller is requesting a restart we reset our
// bookmark of how far we got in the enumeration.
session->LastEnumEntry = NULL;
// In case we're restarting ensure we don't think we're done.
session->EnumCompleted = FALSE;
// We need to start considering items from the beginning of the list
// retrieved from the backing store.
enumHead = session->EnumHead;
}
else
{
// We are resuming an existing enumeration session. Note that
// session->LastEnumEntry may be NULL. That is okay; it means
// we got all the entries the last time this callback was invoked.
// Returning S_OK without adding any new entries to the
// enumParams->DirEntryBufferHandle buffer signals ProjFS that the
// enumeration has returned everything it can.
enumHead = session->LastEnumEntry;
}
if (enumHead == NULL)
{
// There are no items to return. Remember that we've returned everything
// we can.
session->EnumCompleted = TRUE;
}
else
{
MY_ENUM_ENTRY* thisEntry = enumHead;
while (thisEntry != NULL)
{
// We'll insert the entry into the return buffer if it matches
// the search expression captured for this enumeration session.
if (PrjFileNameMatch(thisEntry->Name, session->SearchExpression))
{
PRJ_FILE_BASIC_INFO fileBasicInfo = {};
fileBasicInfo.IsDirectory = thisEntry->IsDirectory;
fileBasicInfo.FileSize = thisEntry->FileSize;
// Format the entry for return to ProjFS.
if (S_OK != PrjFillDirEntryBuffer(thisEntry->Name,
&fileBasicInfo,
enumParams->DirEntryBufferHandle))
{
// We couldn't add this entry to the buffer; remember where we left
// off for the next time we're called for this enumeration session.
session->LastEnumEntry = thisEntry;
hr = S_OK;
goto CompleteCallback;
}
}
thisEntry = thisEntry->Next;
}
// We reached the end of the list of entries; remember that we've returned
// everything we can.
session->EnumCompleted = TRUE;
}
CompleteCallback:
// Signal ProjFS that we've completed this callback. Since this is an enumeration
// we use the extendedParameters parameter to PrjCompleteCommand.
PRJ_COMPLETE_COMMAND_EXTENDED_PARAMETERS extendedParams = {};
extendedParams.CommandType = PRJ_COMPLETE_COMMAND_TYPE_ENUMERATION;
extendedParams.enumeration.DirEntryBufferHandle = enumParams->DirEntryBufferHandle;
PrjCompleteCommand(enumParams->NamespaceVirtualizationContext,
enumParams->CommandId,
hr,
&extendedParams);
MyUntrackEnumForCancellation(enumParams->CommandId);
free(enumParams);
// ThreadProc returns 0 on successful completion.
return 0;
}
上記のサンプル コードで動作するPRJ_CANCEL_COMMAND_CBの簡単な例を次に示します。
void
MyCancelCommandCallback(
_In_ const PRJ_CALLBACK_DATA* callbackData
)
{
// MyMarkEnumForCancellation is a routine the provider might implement to
// mark a pended enumeration callback as cancelled. If the given CommandId
// is not found, it is not an error. It may not yet have been tracked or
// it may already have completed and been untracked.
MyMarkEnumForCancellation(callbackData->CommandId);
}
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示