Função CoCreateFreeThreadedMarshaler (combaseapi.h)

  • Artigo

Cria um objeto agregável capaz de realizar marshaling dependente de contexto.

Sintaxe

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

Parâmetros

[in] punkOuter

Um ponteiro para o IUnknown controlador do objeto de agregação.

[out] ppunkMarshal

Endereço da variável de ponteiro que recebe o ponteiro de interface para o marshaler agregável.

Retornar valor

Essa função pode retornar o valor retornado padrão E_OUTOFMEMORY, bem como o valor a seguir.

Código de retorno Descrição
S_OK
 O marshaler foi criado.

Comentários

A função CoCreateFreeThreadedMarshaler permite que um objeto marshaling eficientemente ponteiros de interface entre threads no mesmo processo. Se os objetos não derem suporte ao marshaling interthread, você não precisará chamar essa função. Ele destina-se ao uso por servidores DLL de thread livre que devem ser acessados diretamente por todos os threads em um processo, até mesmo os threads associados a apartments de thread único. Ele realiza marshaling personalizado do ponteiro de memória real para outros apartamentos como um falso "proxy" e, assim, dá acesso direto a todos os chamadores, mesmo que eles não sejam livres.

A função CoCreateFreeThreadedMarshaler executa as seguintes tarefas:

  1. Cria um objeto marshaler de thread livre.
  2. Agrega esse marshaler ao objeto especificado pelo parâmetro punkOuter . Normalmente, esse objeto é aquele cujos ponteiros de interface devem ser empacotados.
A implementação do objeto de agregação de IMarshal deve delegar chamadas QueryInterface para IID_IMarshal ao IUnknown do marshaler de thread livre. Ao receber uma chamada, o marshaler de thread livre executa as seguintes tarefas:
  1. Verifica o contexto de destino especificado pelo parâmetro dwDestContext da função CoMarshalInterface.
  2. Se o contexto de destino for MSHCTX_INPROC, copiará o ponteiro da interface para o fluxo de marshaling.
  3. Se o contexto de destino for qualquer outro valor, localizará ou criará uma instância do marshaler padrão (padrão) do COM e delega o marshaling para ele.
Os valores de dwDestContext vêm da enumeração MSHCTX . MSHCTX_INPROC indica que o ponteiro da interface deve ter marshaling entre threads diferentes no mesmo processo. Como ambos os threads têm acesso ao mesmo espaço de endereço, o thread do cliente pode desreferenciar o ponteiro diretamente em vez de precisar direcionar chamadas para um proxy. Em todos os outros casos, um proxy é necessário, portanto, CoCreateFreeThreadedMarshaler delega o trabalho de marshaling para a implementação padrão do COM.

É necessário ter muito cuidado ao usar a função CoCreateFreeThreadedMarshaler . Isso ocorre porque o desempenho de objetos que agregam o marshaler de thread livre é obtido por meio de uma violação calculada das regras de COM, com o risco sempre presente de comportamento indefinido, a menos que o objeto opere dentro de determinadas restrições. As restrições mais importantes são:

  • Um objeto marshaler de thread livre não pode conter ponteiros diretos para interfaces em um objeto que não agrega o marshaler de thread livre como parte de seu estado. Se o objeto usar referências diretas a objetos de agregação de thread único comuns, ele poderá interromper sua única propriedade threaded. Se o objeto usar referências diretas a objetos de agregação multithread comuns, esses objetos poderão se comportar de maneiras que não mostram nenhuma sensibilidade às necessidades de clientes de agregação direta de thread único. Por exemplo, esses objetos podem girar novos threads e passar parâmetros para os threads que são referências a objetos de agregação de thread único comuns.
  • Um objeto marshaler de thread livre não pode conter referências a proxies para objetos em outros apartments. Os proxies são sensíveis ao modelo de threading e podem retornar RPC_E_WRONG_THREAD se chamados pelo cliente errado.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho combaseapi.h (inclua Objbase.h)
Biblioteca Ole32.lib
DLL Ole32.dll

Confira também

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream