Asenkron Callback İşleme
bir istemci, sağlayıcının sanallaştırma kökü altındaki dosya ve dizinlerle etkileşime geçtiğinde, bu etkileşimler genellikle sağlayıcının geri çağırmalarının çağrılmasını sağlar. ProjFS, çekirdek modundan ProjFS kullanıcı modu kitaplığına bir ileti göndererek sağlayıcı geri çağırmalarını çağırır; burada bir çalışan iş parçacığı iletiyi alır ve uygun geri aramayı çağırır. Geri çağırma işlemi döndükten sonra, iş parçacığı çekirdek modundan başka bir iletinin gelmesini bekler. Tüm çalışan iş parçacıkları sağlayıcı geri çağırma kodunu yürütmekle meşgulse, bir çalışan iş parçacığı iletiyi alıp ilgili geri çağırmayı çağırana kadar geri çağırmayı tetikleyen diğer tüm istemci G/Ç'leri engellenir. Sağlayıcı başlatıldığında, seçenekleri parametresi aracılığıyla, ProjFS'nin geri çağırmalara hizmet vermesi için oluşturulmasını istediği çalışan iş parçacığı sayısını PrjStartVirtualizingile belirleyebilir. Sağlayıcı, geri çağrıları eşzamansız olarak hizmet vererek ileti alan iş parçacıklarının verimliliğini artırabilir.
Sağlayıcı PrjStartVirtualizing için seçenekleri parametresini belirtmezse veya seçenekleri parametresinin ConcurrentThreadCount üyesi için 0 belirtirse, ProjFS ConcurrentThreadCount değeri için sistemdeki mantıksal işlemci sayısını kullanır.
Sağlayıcı PrjStartVirtualizing parametresine seçenekleri belirtmezse veya seçenekleri parametresinin PoolThreadCount üyesi için 0 belirtiyorsa, ProjFS PoolThreadCount değeri için ConcurrentThreadCount değerinin iki katını kullanır.
Bir sağlayıcı, geri çağırma fonksiyonlarını, kendi geri çağırmalarından HRESULT_FROM_WIN32(ERROR_IO_PENDING) döndürerek ve daha sonra PrjCompleteCommandkullanarak tamamlayarak zaman uyumsuz olarak gerçekleştirir. Geri çağırmaları zaman uyumsuz olarak işleyen bir sağlayıcı, PRJ_CANCEL_COMMAND_CB geri çağırma uygulayarak geri çağırma iptalini de desteklemelidir.
ProjFS bir sağlayıcının geri çağırmasını çağırdığında, geri çağırmanın callbackData parametresinin CommandId üyesini kullanarak geri çağırmanın özel çağrısını tanımlar. Sağlayıcı, bu callback'i zaman uyumsuz olarak işlemeye karar verirse, CommandId üyesinin değerini depolamalı ve callback'ten HRESULT_FROM_WIN32(ERROR_IO_PENDING) dönmelidir. Sağlayıcı geri çağırma işlemini tamamladıktan sonra PrjCompleteCommandçağrısı yaparak depolanan tanımlayıcıyı commandId parametresine geçirir. Bu, ProjFS'ye hangi geri çağırmanın tamamlandığını bildirir.
PRJ_CANCEL_COMMAND_CB geri çağırmayı uygulayan bir sağlayıcının henüz tamamlanmamış olan geri çağırmaları izlemesi gerekir. Sağlayıcı bu geri çağırmayı alırsa, bu geri çağırmalardan birinin çağrılmasına neden olan G/Ç'nin, ya açık bir şekilde iptal edilmiş olduğunu ya da yürütüldüğü iş parçacığı sonlandırıldığı için iptal edildiğini gösterir. Sağlayıcı, CommandId tarafından tanımlanan geri çağırma işlemini mümkün olan en kısa sürede iptal etmelidir.
ProjFS, belirli bir CommandId için yalnızca iptal edilecek geri çağırma çağrıldıktan sonra PRJ_CANCEL_COMMAND_CB çağırsa da, iptal ve özgün çağırma çok iş parçacıklı bir sağlayıcıda eşzamanlı olarak çalıştırılabilir. Sağlayıcının bu durumu düzgün bir şekilde işleyebilmesi gerekir.
Aşağıdaki örnek, asenkron geri çağırma işlemeyi göstermek için değiştirilmiş dosya ve dizinleri listeleme konusu için verilen örneğin bir sürümüdür.
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;
}
Yukarıdaki örnek kodla çalışan kısa bir örnek PRJ_CANCEL_COMMAND_CB aşağıda verilmiştir.
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);
}