Procédure pas à pas : utilisation du runtime d'accès concurrentiel routage dans une application COM
Ce document montre comment utiliser le runtime d'accès concurrentiel dans une application qui utilise le Modèle COM.
Composants requis
Lisez les documents suivants avant de démarrer cette procédure pas-à-pas :
Pour plus d'informations sur le modèle COM, consultez COM (Component Object Model).
Gestion de la durée de vie de la bibliothèque COM
Bien que l'utilisation de COM avec le runtime d'accès concurrentiel suive les mêmes principes que tout autre mécanisme d'accès concurrentiel, les indications suivantes peuvent vous aider à utiliser ces bibliothèques ensemble efficacement.
Un thread doit appeler CoInitializeEx avant d'utiliser la bibliothèque COM.
Un thread peut appeler CoInitializeEx plusieurs fois, tant qu'il fournit les mêmes arguments à chaque appel.
Pour chaque appel à CoInitializeEx, un thread doit également appeler CoUninitialize. En d'autres termes, les appels à CoInitializeEx et CoUninitialize doivent être équilibrés.
Pour basculer d'un thread cloisonné sur un autre, un thread doit complètement libérer la bibliothèque COM avant d'appeler CoInitializeEx avec la nouvelle spécification de threading.
D'autres principes COM s'appliquent lorsque vous utilisez COM avec le runtime d'accès concurrentiel. Par exemple, une application qui crée un objet dans un thread cloisonné (STA, single-threaded apartment) et marshale cet objet à un autre apartment doit également fournir une boucle de messages pour traiter les messages entrants. Vous devez également garder à l'esprit que le marshaling d'objets entre les apartments risque de diminuer les performances.
Utilisation de COM avec la bibliothèque de modèles parallèles
Lorsque vous utilisez COM avec un composant de la bibliothèque de modèles parallèles (PPL), tel qu'un groupe de tâches ou un algorithme parallèle, appelez CoInitializeEx avant d'utiliser la bibliothèque COM pendant chaque tâche ou itération, et appelez CoUninitialize avant la fin de chaque tâche ou itération. L'exemple suivant indique comment gérer la durée de vie de la bibliothèque COM avec un objet Concurrency::structured_task_group.
structured_task_group tasks;
// Create and run a task.
auto task = make_task([] {
// Initialize the COM library on the current thread.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
// TODO: Perform task here.
// Free the COM library.
CoUninitialize();
});
tasks.run(task);
// TODO: Run additional tasks here.
// Wait for the tasks to finish.
tasks.wait();
Vous devez vous assurer que la bibliothèque COM est libérée correctement lorsqu'une tâche ou un algorithme parallèle est annulé, ou lorsque le corps de la tâche lève une exception. Pour garantir que la tâche appelle CoUninitialize avant de s'arrêter, utilisez un bloc try-finally ou un modèle RAII (Resource Acquisition Is Initialization). L'exemple suivant utilise un bloc try-finally pour libérer la bibliothèque COM lorsque la tâche se termine ou est annulée, ou lorsqu'une exception est levée.
structured_task_group tasks;
// Create and run a task.
auto task = make_task([] {
bool coinit = false;
__try {
// Initialize the COM library on the current thread.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
coinit = true;
// TODO: Perform task here.
}
__finally {
// Free the COM library.
if (coinit)
CoUninitialize();
}
});
tasks.run(task);
// TODO: Run additional tasks here.
// Wait for the tasks to finish.
tasks.wait();
L'exemple suivant utilise les modèles RAII pour définir la classe CCoInitializer, qui gère la durée de vie de la bibliothèque COM dans une portée donnée.
// An exception-safe wrapper class that manages the lifetime
// of the COM library in a given scope.
class CCoInitializer
{
public:
explicit CCoInitializer(DWORD dwCoInit = COINIT_APARTMENTTHREADED)
: _coinitialized(false)
{
// Initialize the COM library on the current thread.
HRESULT hr = CoInitializeEx(NULL, dwCoInit);
if (FAILED(hr))
throw hr;
_coinitialized = true;
}
~CCoInitializer()
{
// Free the COM library.
if (_coinitialized)
CoUninitialize();
}
private:
// Flags whether COM was properly initialized.
bool _coinitialized;
// Hide copy constructor and assignment operator.
CCoInitializer(const CCoInitializer&);
CCoInitializer& operator=(const CCoInitializer&);
};
Vous pouvez utiliser la classe CCoInitializer pour libérer automatiquement la bibliothèque COM lorsque la tâche s'arrête, de la façon suivante.
structured_task_group tasks;
// Create and run a task.
auto task = make_task([] {
// Enable COM for the lifetime of the task.
CCoInitializer coinit(COINIT_MULTITHREADED);
// TODO: Perform task here.
// The CCoInitializer object frees the COM library
// when the task exits.
});
tasks.run(task);
// TODO: Run additional tasks here.
// Wait for the tasks to finish.
tasks.wait();
Pour plus d'informations sur l'annulation du runtime d'accès concurrentiel, consultez Annulation dans la bibliothèque de modèles parallèles.
Utilisation de COM avec les agents asynchrones
Lorsque vous utilisez COM avec les agents asynchrones, appelez CoInitializeEx avant d'utiliser la bibliothèque COM dans la méthode Concurrency::agent::run pour votre agent. Appelez ensuite CoUninitialize avant le retour de la méthode run. N'utilisez pas de routines de gestion COM dans le constructeur ou le destructeur de votre agent, et ne substituez pas les méthodes Concurrency::agent::start ou Concurrency::agent::done, car ces méthodes sont appelées par un thread différent de la méthode run.
L'exemple suivant montre une classe d'agent de base appelée CCoAgent, qui gère la bibliothèque COM dans la méthode run.
class CCoAgent : public agent
{
protected:
void run()
{
// Initialize the COM library on the current thread.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
// TODO: Perform work here.
// Free the COM library.
CoUninitialize();
// Set the agent to the finished state.
done();
}
};
Un exemple complet est fourni à une étape ultérieure de cette procédure.
Utilisation de COM avec les tâches légères
Le document Planificateur de tâches (runtime d'accès concurrentiel) décrit le rôle des tâches légères dans le runtime d'accès concurrentiel. Vous pouvez utiliser COM avec une tâche légère, de la même manière qu'avec toute routine de thread que vous passez à la fonction CreateThread dans l'API Windows. L'exemple suivant le démontre.
// A basic lightweight task that you schedule directly from a
// Scheduler or ScheduleGroup object.
void ThreadProc(void* data)
{
// Initialize the COM library on the current thread.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
// TODO: Perform work here.
// Free the COM library.
CoUninitialize();
}
Exemple d'application COM
Cette section montre une application COM complète qui utilise l'interface IScriptControl pour exécuter un script qui calcule le nème nombre de Fibonacci. Cet exemple appelle en premier le script du thread principal, puis utilise la bibliothèque de modèles parallèles et les agents pour appeler le script simultanément.
Considérez la fonction d'assistance suivante, RunScriptProcedure qui appelle une procédure dans un objet IScriptControl.
// Calls a procedure in an IScriptControl object.
template<size_t ArgCount>
_variant_t RunScriptProcedure(IScriptControlPtr pScriptControl,
_bstr_t& procedureName, array<_variant_t, ArgCount>& arguments)
{
// Create a 1-dimensional, 0-based safe array.
SAFEARRAYBOUND rgsabound[] = { ArgCount, 0 };
CComSafeArray<VARIANT> sa(rgsabound, 1U);
// Copy the arguments to the safe array.
LONG lIndex = 0;
for_each(arguments.begin(), arguments.end(), [&](_variant_t& arg) {
HRESULT hr = sa.SetAt(lIndex, arg);
if (FAILED(hr))
throw hr;
++lIndex;
});
// Call the procedure in the script.
return pScriptControl->Run(procedureName, &sa.m_psa);
}
La fonction wmain crée un objet IScriptControl, lui ajoute du code de script qui calcule le nème nombre de Fibonacci, puis appelle la fonction RunScriptProcedure pour exécuter ce script.
int wmain()
{
HRESULT hr;
// Enable COM on this thread for the lifetime of the program.
CCoInitializer coinit(COINIT_MULTITHREADED);
// Create the script control.
IScriptControlPtr pScriptControl(__uuidof(ScriptControl));
// Set script control properties.
pScriptControl->Language = "JScript";
pScriptControl->AllowUI = TRUE;
// Add script code that computes the nth Fibonacci number.
hr = pScriptControl->AddCode(
"function fib(n) { if (n<2) return n; else return fib(n-1) + fib(n-2); }" );
if (FAILED(hr))
return hr;
// Test the script control by computing the 15th Fibonacci number.
wcout << endl << L"Main Thread:" << endl;
LONG lValue = 15;
array<_variant_t, 1> args = { _variant_t(lValue) };
_variant_t result = RunScriptProcedure(
pScriptControl,
_bstr_t("fib"),
args);
// Print the result.
wcout << L"fib(" << lValue << L") = " << result.lVal << endl;
return S_OK;
}
Appel du script depuis la bibliothèque de modèles parallèles
La fonction suivante, ParallelFibonacci, utilise l'algorithme Concurrency::parallel_for pour appeler le script en parallèle. Cette fonction utilise la classe CCoInitializer pour gérer la durée de vie de la bibliothèque COM pendant chaque itération de la tâche.
// Computes multiple Fibonacci numbers in parallel by using
// the parallel_for algorithm.
HRESULT ParallelFibonacci(IScriptControlPtr pScriptControl)
{
try {
parallel_for(10L, 20L, [&pScriptControl](LONG lIndex)
{
// Enable COM for the lifetime of the task.
CCoInitializer coinit(COINIT_MULTITHREADED);
// Call the helper function to run the script procedure.
array<_variant_t, 1> args = { _variant_t(lIndex) };
_variant_t result = RunScriptProcedure(
pScriptControl,
_bstr_t("fib"),
args);
// Print the result.
wstringstream ss;
ss << L"fib(" << lIndex << L") = " << result.lVal << endl;
wcout << ss.str();
});
}
catch (HRESULT hr) {
return hr;
}
return S_OK;
}
Pour utiliser la fonction ParallelFibonacci avec cet exemple, ajoutez le code suivant avant le retour de la fonction wmain.
// Use the parallel_for algorithm to compute multiple
// Fibonacci numbers in parallel.
wcout << endl << L"Parallel Fibonacci:" << endl;
if (FAILED(hr = ParallelFibonacci(pScriptControl)))
return hr;
Appel du script par un agent
L'exemple suivant montre la classe FibonacciScriptAgent, qui appelle une procédure de script pour calculer le nème nombre de Fibonacci. La classe FibonacciScriptAgent utilise le passage de message pour recevoir du programme principal des valeurs d'entrée de la fonction de script. La méthode run gère la durée de vie de la bibliothèque COM tout au long de la tâche.
// A basic agent that calls a script procedure to compute the
// nth Fibonacci number.
class FibonacciScriptAgent : public agent
{
public:
FibonacciScriptAgent(IScriptControlPtr pScriptControl, ISource<LONG>& source)
: _pScriptControl(pScriptControl)
, _source(source) { }
public:
// Retrieves the result code.
HRESULT GetHRESULT()
{
return receive(_result);
}
protected:
void run()
{
// Initialize the COM library on the current thread.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
// Read values from the message buffer until
// we receive the sentinel value.
LONG lValue;
while ((lValue = receive(_source)) != Sentinel)
{
try {
// Call the helper function to run the script procedure.
array<_variant_t, 1> args = { _variant_t(lValue) };
_variant_t result = RunScriptProcedure(
_pScriptControl,
_bstr_t("fib"),
args);
// Print the result.
wstringstream ss;
ss << L"fib(" << lValue << L") = " << result.lVal << endl;
wcout << ss.str();
}
catch (HRESULT hr) {
send(_result, hr);
break;
}
}
// Set the result code (does nothing if a value is already set).
send(_result, S_OK);
// Free the COM library.
CoUninitialize();
// Set the agent to the finished state.
done();
}
public:
// Signals the agent to terminate.
static const LONG Sentinel = 0L;
private:
// The IScriptControl object that contains the script procedure.
IScriptControlPtr _pScriptControl;
// Message buffer from which to read arguments to the
// script procedure.
ISource<LONG>& _source;
// The result code for the overall operation.
single_assignment<HRESULT> _result;
};
La fonction suivante, AgentFibonacci, crée plusieurs objets FibonacciScriptAgent et utilise le passage de message pour envoyer plusieurs valeurs d'entrée à ces objets.
// Computes multiple Fibonacci numbers in parallel by using
// asynchronous agents.
HRESULT AgentFibonacci(IScriptControlPtr pScriptControl)
{
// Message buffer to hold arguments to the script procedure.
unbounded_buffer<LONG> values;
// Create several agents.
array<agent*, 3> agents =
{
new FibonacciScriptAgent(pScriptControl, values),
new FibonacciScriptAgent(pScriptControl, values),
new FibonacciScriptAgent(pScriptControl, values),
};
// Start each agent.
for_each(agents.begin(), agents.end(), [](agent* a) {
a->start();
});
// Send a few values to the agents.
send(values, 30L);
send(values, 22L);
send(values, 10L);
send(values, 12L);
// Send a sentinel value to each agent.
for_each(agents.begin(), agents.end(), [&values](agent* _) {
send(values, FibonacciScriptAgent::Sentinel);
});
// Wait for all agents to finish.
agent::wait_for_all(3, &agents[0]);
// Determine the result code.
HRESULT hr = S_OK;
for_each(agents.begin(), agents.end(), [&hr](agent* a) {
HRESULT hrTemp;
if (FAILED(hrTemp =
reinterpret_cast<FibonacciScriptAgent*>(a)->GetHRESULT()))
{
hr = hrTemp;
}
});
// Clean up.
for_each(agents.begin(), agents.end(), [](agent* a) {
delete a;
});
return hr;
}
Pour utiliser la fonction AgentFibonacci avec cet exemple, ajoutez le code suivant avant le retour de la fonction wmain.
// Use asynchronous agents to compute multiple
// Fibonacci numbers in parallel.
wcout << endl << L"Agent Fibonacci:" << endl;
if (FAILED(hr = AgentFibonacci(pScriptControl)))
return hr;
Exemple complet
Le code suivant montre l'exemple complet, qui utilise des algorithmes parallèles et des agents asynchrones pour appeler une procédure de script qui calcule des nombres de Fibonacci.
// parallel-scripts.cpp
// compile with: /EHsc
#include <agents.h>
#include <ppl.h>
#include <array>
#include <sstream>
#include <iostream>
#include <atlsafe.h>
// TODO: Change this path if necessary.
#import "C:\windows\system32\msscript.ocx"
using namespace Concurrency;
using namespace MSScriptControl;
using namespace std;
// An exception-safe wrapper class that manages the lifetime
// of the COM library in a given scope.
class CCoInitializer
{
public:
explicit CCoInitializer(DWORD dwCoInit = COINIT_APARTMENTTHREADED)
: _coinitialized(false)
{
// Initialize the COM library on the current thread.
HRESULT hr = CoInitializeEx(NULL, dwCoInit);
if (FAILED(hr))
throw hr;
_coinitialized = true;
}
~CCoInitializer()
{
// Free the COM library.
if (_coinitialized)
CoUninitialize();
}
private:
// Flags whether COM was properly initialized.
bool _coinitialized;
// Hide copy constructor and assignment operator.
CCoInitializer(const CCoInitializer&);
CCoInitializer& operator=(const CCoInitializer&);
};
// Calls a procedure in an IScriptControl object.
template<size_t ArgCount>
_variant_t RunScriptProcedure(IScriptControlPtr pScriptControl,
_bstr_t& procedureName, array<_variant_t, ArgCount>& arguments)
{
// Create a 1-dimensional, 0-based safe array.
SAFEARRAYBOUND rgsabound[] = { ArgCount, 0 };
CComSafeArray<VARIANT> sa(rgsabound, 1U);
// Copy the arguments to the safe array.
LONG lIndex = 0;
for_each(arguments.begin(), arguments.end(), [&](_variant_t& arg) {
HRESULT hr = sa.SetAt(lIndex, arg);
if (FAILED(hr))
throw hr;
++lIndex;
});
// Call the procedure in the script.
return pScriptControl->Run(procedureName, &sa.m_psa);
}
// Computes multiple Fibonacci numbers in parallel by using
// the parallel_for algorithm.
HRESULT ParallelFibonacci(IScriptControlPtr pScriptControl)
{
try {
parallel_for(10L, 20L, [&pScriptControl](LONG lIndex)
{
// Enable COM for the lifetime of the task.
CCoInitializer coinit(COINIT_MULTITHREADED);
// Call the helper function to run the script procedure.
array<_variant_t, 1> args = { _variant_t(lIndex) };
_variant_t result = RunScriptProcedure(
pScriptControl,
_bstr_t("fib"),
args);
// Print the result.
wstringstream ss;
ss << L"fib(" << lIndex << L") = " << result.lVal << endl;
wcout << ss.str();
});
}
catch (HRESULT hr) {
return hr;
}
return S_OK;
}
// A basic agent that calls a script procedure to compute the
// nth Fibonacci number.
class FibonacciScriptAgent : public agent
{
public:
FibonacciScriptAgent(IScriptControlPtr pScriptControl, ISource<LONG>& source)
: _pScriptControl(pScriptControl)
, _source(source) { }
public:
// Retrieves the result code.
HRESULT GetHRESULT()
{
return receive(_result);
}
protected:
void run()
{
// Initialize the COM library on the current thread.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
// Read values from the message buffer until
// we receive the sentinel value.
LONG lValue;
while ((lValue = receive(_source)) != Sentinel)
{
try {
// Call the helper function to run the script procedure.
array<_variant_t, 1> args = { _variant_t(lValue) };
_variant_t result = RunScriptProcedure(
_pScriptControl,
_bstr_t("fib"),
args);
// Print the result.
wstringstream ss;
ss << L"fib(" << lValue << L") = " << result.lVal << endl;
wcout << ss.str();
}
catch (HRESULT hr) {
send(_result, hr);
break;
}
}
// Set the result code (does nothing if a value is already set).
send(_result, S_OK);
// Free the COM library.
CoUninitialize();
// Set the agent to the finished state.
done();
}
public:
// Signals the agent to terminate.
static const LONG Sentinel = 0L;
private:
// The IScriptControl object that contains the script procedure.
IScriptControlPtr _pScriptControl;
// Message buffer from which to read arguments to the
// script procedure.
ISource<LONG>& _source;
// The result code for the overall operation.
single_assignment<HRESULT> _result;
};
// Computes multiple Fibonacci numbers in parallel by using
// asynchronous agents.
HRESULT AgentFibonacci(IScriptControlPtr pScriptControl)
{
// Message buffer to hold arguments to the script procedure.
unbounded_buffer<LONG> values;
// Create several agents.
array<agent*, 3> agents =
{
new FibonacciScriptAgent(pScriptControl, values),
new FibonacciScriptAgent(pScriptControl, values),
new FibonacciScriptAgent(pScriptControl, values),
};
// Start each agent.
for_each(agents.begin(), agents.end(), [](agent* a) {
a->start();
});
// Send a few values to the agents.
send(values, 30L);
send(values, 22L);
send(values, 10L);
send(values, 12L);
// Send a sentinel value to each agent.
for_each(agents.begin(), agents.end(), [&values](agent* _) {
send(values, FibonacciScriptAgent::Sentinel);
});
// Wait for all agents to finish.
agent::wait_for_all(3, &agents[0]);
// Determine the result code.
HRESULT hr = S_OK;
for_each(agents.begin(), agents.end(), [&hr](agent* a) {
HRESULT hrTemp;
if (FAILED(hrTemp =
reinterpret_cast<FibonacciScriptAgent*>(a)->GetHRESULT()))
{
hr = hrTemp;
}
});
// Clean up.
for_each(agents.begin(), agents.end(), [](agent* a) {
delete a;
});
return hr;
}
int wmain()
{
HRESULT hr;
// Enable COM on this thread for the lifetime of the program.
CCoInitializer coinit(COINIT_MULTITHREADED);
// Create the script control.
IScriptControlPtr pScriptControl(__uuidof(ScriptControl));
// Set script control properties.
pScriptControl->Language = "JScript";
pScriptControl->AllowUI = TRUE;
// Add script code that computes the nth Fibonacci number.
hr = pScriptControl->AddCode(
"function fib(n) { if (n<2) return n; else return fib(n-1) + fib(n-2); }" );
if (FAILED(hr))
return hr;
// Test the script control by computing the 15th Fibonacci number.
wcout << L"Main Thread:" << endl;
long n = 15;
array<_variant_t, 1> args = { _variant_t(n) };
_variant_t result = RunScriptProcedure(
pScriptControl,
_bstr_t("fib"),
args);
// Print the result.
wcout << L"fib(" << n << L") = " << result.lVal << endl;
// Use the parallel_for algorithm to compute multiple
// Fibonacci numbers in parallel.
wcout << endl << L"Parallel Fibonacci:" << endl;
if (FAILED(hr = ParallelFibonacci(pScriptControl)))
return hr;
// Use asynchronous agents to compute multiple
// Fibonacci numbers in parallel.
wcout << endl << L"Agent Fibonacci:" << endl;
if (FAILED(hr = AgentFibonacci(pScriptControl)))
return hr;
return S_OK;
}
Cet exemple génère l'exemple de sortie suivant :
Main Thread:
fib(15) = 610
Parallel Fibonacci:
fib(15) = 610
fib(10) = 55
fib(16) = 987
fib(18) = 2584
fib(11) = 89
fib(17) = 1597
fib(19) = 4181
fib(12) = 144
fib(13) = 233
fib(14) = 377
Agent Fibonacci:
fib(30) = 832040
fib(22) = 17711
fib(10) = 55
fib(12) = 144
Compilation du code
Copiez l'exemple de code et collez-le dans un projet Visual Studio, ou collez-le dans un fichier nommé parallel-scripts.cpp puis exécutez la commande suivante dans une fenêtre d'invite de commandes Visual Studio 2010.
cl.exe /EHsc parallel-scripts.cpp /link ole32.lib
Voir aussi
Concepts
Procédures pas à pas relatives au runtime d'accès concurrentiel
Parallélisme des tâches (runtime d'accès concurrentiel)
Gestion des exceptions dans le runtime d'accès concurrentiel