MessageChannel - Referência da API Adobe ActionScript® 3 (AS3 )

Pacote	flash.system
Classe	public final class MessageChannel
Herança	MessageChannel EventDispatcher Object

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

A classe MessageChannel fornece um mecanismo para um worker se comunicar com outro worker. Um canal de mensagem é um canal de comunicação unidirecional. O worker enviado pelo canal de mensagem utiliza o canal de mensagem para enviar objetos ao worker destinatário. Um objeto MessageChannel é o único modo de enviar uma mensagem entre workers que enviam eventos, indicando ao destinatário que a mensagem está disponível. Outros mecanismos para compartilhamento de dados permitem que um valor seja definido, mas não fornecem um evento para notificar você dos dados alterados.

Cada objeto MessageChannel contém uma fila de objetos de mensagens enviadas do worker de envio ao worker de destino. Cada chamada para o send() adiciona um objeto à fila. Cada chamada ao receive() recupera o objeto de mensagem mais antigo da fila.

Não é possível criar instâncias MessageChannel fazendo uma chamada para o construtor MessageChannel(). Para criar uma instância MessageChannel, faça uma chamada para o método createMessageChannel() do objeto Worker que enviará mensagens ao canal, passando o objeto Worker como um argumento.

O fluxo de trabalho típico para enviar mensagens com o objeto MessageChannel é da seguinte maneira:

Faça uma chamada ao método createMessageChannel() do worker de envio para criar o canal de mensagem.

    // In the sending worker swf
    var sendChannel:MessageChannel;
    sendChannel = Worker.current.createMessageChannel(receivingWorker);

Passe o canal de mensagem ao outro worker, efetuando uma chamada para Worker.setSharedProperty() ou enviando-o través de um canal de mensagem existente.
```
    receivingWorker.setSharedProperty("incomingChannel", sendChannel);
```

Código no worker de destino registra um ouvindo com o objeto MessageChannel para o evento channelMessage

    // In the receiving worker swf
    var incomingChannel:MessageChannel;
    incomingChannel = Worker.current.getSharedProperty("incomingChannel");
    incomingChannel.addEventListener(Event.CHANNEL_MESSAGE, handleIncomingMessage);

Código no worker de envio envia uma mensagem efetuando uma chamada ao método send()
```
    // In the sending worker swf
    sendChannel.send("This is a message");
```

O runtime efetua uma chamada ao gerenciador do evento no código do worker de destino, indicando que a mensagem foi enviada

    // In the receiving worker swf
    // This method is called when the message channel gets a message
    private function handleIncomingMessage(event:Event):void
    {
        // Do something with the message, as shown in the next code listing
    }

Código no worker de destino efetua uma chamada ao método receive() para obter a mensagem O objeto retornado pelo método receive() possui o mesmo tipo de dados do objeto passado ao método send().
```
    var message:String = incomingChannel.receive() as String;
```

Além do fluxo de trabalho assíncrono descrito acima, você pode utilizar um fluxo de trabalho alternativo com o métodoreceive() para pausar o código no worker de destino e esperar até que a mensagem seja enviada. Veja a descrição do método receive() para obter mais informações.

A classe MessageChannel é um dos tipos de objeto especial compartilhado entre os workers, em vez de copiados entre eles. Quando você passa um canal de mensagem de um worker a outro efetuando uma chamada ao método setSharedProperty() do objeto do Worker ou usando um canal MessageChannel, ambos os workers têm referência ao mesmo objeto MessageChannel na memória do runtime.

Elementos da API relacionados

Classe Worker
Worker.createMessageChannel() method

Propriedades públicas

Ocultar propriedades públicas herdadas

Mostrar propriedades públicas herdadas

	Propriedade		Definido por
		constructor : Object Uma referência ao objeto de classe ou à função de construtor de uma determinada ocorrência de objeto.	Object
		messageAvailable : Boolean [somente leitura] Indica se a MessageChannel possui uma ou mais mensagens do worker de envio em sua fila interna de mensagens.	MessageChannel
		state : String [somente leitura] Indica que o estado atual do objeto MessageChannel (abrir, fechando ou fechar).	MessageChannel

Métodos públicos

Ocultar métodos públicos herdados

Mostrar métodos públicos herdados

	Método		Definido por
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void [substituir] Registra um objeto de ouvinte de evento em um objeto EventDispatcher, de forma que o ouvinte receba a notificação de um evento.	MessageChannel
		close():void Instrui o MessageChannel atual para ser fechado depois que todas as mensagens forem recebidas.	MessageChannel
		dispatchEvent(event:Event):Boolean Envia um evento para o fluxo de eventos.	EventDispatcher
		hasEventListener(type:String):Boolean Verifica se o objeto EventDispatcher tem ouvintes registrados para um tipo específico de evento.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indica se um objeto tem uma propriedade especificada definida.	Object
		isPrototypeOf(theClass:Object):Boolean Indica se uma ocorrência da classe Object está na cadeia de protótipos do objeto especificado como o parâmetro.	Object
		propertyIsEnumerable(name:String):Boolean Indica se a propriedade especificada existe e é enumerável.	Object
		receive(blockUntilReceived:Boolean = false):* Recupera um objeto de mensagem único da fila de mensagens enviado através deste canal de mensagens.	MessageChannel
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void [substituir] Remove um ouvinte do objeto EventDispatcher.	MessageChannel
		send(arg:*, queueLimit:int = -1):void Envia um objeto a partir do worker de envio, adicionando-o à fila da mensagem ao worker de destino.	MessageChannel
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Define a disponibilidade de uma propriedade dinâmica para operações de repetição.	Object
		toLocaleString():String Retorna a representação da string deste objeto, formatado segundo as convenções específicas para a localidade.	Object
		toString():String [substituir] Retorna a representação de string do objeto especificado.	MessageChannel
		valueOf():Object Retorna o valor primitivo do objeto especificado.	Object
		willTrigger(type:String):Boolean Verifica se um ouvinte de evento está registrado nesse objeto EventDispatcher ou em qualquer um de seus ancestrais para o tipo de evento especificado.	EventDispatcher

Eventos

Clique para obter mais informações sobre eventos

Ocultar eventos herdados

Mostrar eventos herdados

	Resumo	Definido por
activate	[transmissão de evento] Despachado quando o Flash Player ou o aplicativo do AIR ganha o foco do sistema operacional e está se tornando inativo.	EventDispatcher
channelMessage	Enviado cada vez que o worker de envio efetuar uma chamada a este método send() do objeto MessageChannel, indicando que um novo objeto de mensagem está disponível na fila da instância do MessgeChannel.	MessageChannel
channelState	Enviado quando o valor da propriedade do estado do canal de mensagem é alterado.	MessageChannel
deactivate	[transmissão de evento] Despachado quando o Flash Player ou o aplicativo do AIR perde o foco do sistema operacional e está se tornando inativo.	EventDispatcher

Detalhes da propriedade

messageAvailable

propriedade

messageAvailable:Boolean [somente leitura]

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Indica se a MessageChannel possui uma ou mais mensagens do worker de envio em sua fila interna de mensagens.

Implementação
public function get messageAvailable():Boolean

state

propriedade

state:String [somente leitura]

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Indica que o estado atual do objeto MessageChannel (abrir, fechando ou fechar). Os possíveis valores para esta propriedade são definidos como constantes na classe MessageChannelState.

Implementação
public function get state():String

Elementos da API relacionados

Classe MessageChannelState

Detalhes do método

addEventListener

()

método

override public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Registra um objeto de ouvinte de evento em um objeto EventDispatcher, de forma que o ouvinte receba a notificação de um evento. Você pode registrar ouvintes de eventos em todos os nós da lista de exibição de um tipo específico de evento, fase e prioridade.

Depois de registrar um ouvinte de evento com êxito, não será possível alterar a respectiva prioridade por meio de chamadas adicionais para o addEventListener(). Para alterar a prioridade de um ouvinte, chame primeiramente o removeListener(). Em seguida, você poderá registrar o ouvinte novamente com o novo nível de prioridade.

Tenha em mente que, após o ouvinte ser registrado, chamadas subsequentes para o addEventListener() com um valor type ou useCapture diferente resultarão na criação de um registro de ouvinte separado. Por exemplo, se você primeiro registrar um ouvinte com o useCapture definido como true, ele escutará apenas durante a fase de captura. Se você chamar o addEventListener() novamente, usando o mesmo objeto de ouvinte, mas com o useCapture definido como false, você terá dois ouvintes distintos: um que escuta durante a fase de captura e outro que escuta durante as fases de destino e de bubbling.

Você não pode registrar um ouvinte de evento apenas para a fase de destino ou a fase de bubbling. Essas fases são emparelhadas durante o registro porque o bubbling se aplica apenas aos ancestral do nó-alvo.

Se você não precisar mais de um ouvinte de evento, remova-o, chamando o removeEventListener(); do contrário, poderão ocorrer problemas de memória. Os ouvintes de evento não são retirados automaticamente da memória porque o coletor de lixo não remove o ouvinte enquanto o objeto de despacho existe (a menos que o parâmetro useWeakReference seja definido para true).

Copiar uma ocorrência do EventDispatcher não copia os ouvintes de eventos a ele anexados. (Se o seu recém-criado nó precisar de um ouvinte de evento, anexe o ouvinte após criar o nó). Entretanto, se você mover uma ocorrência do EventDispatcher, os ouvintes de evento anexados se movimentarão com ele.

Se o ouvinte de evento estiver sendo registrado em um nó enquanto um evento estiver sendo processado nesse nó, o ouvinte de evento não será disparado durante a fase atual, mas poderá ser disparado durante uma fase posterior no fluxo de eventos, como a fase de bubbling.

Se um ouvinte de evento for removido de um nó enquanto um evento estiver sendo processado no nó, ele ainda será disparado pelas ações atuais. Depois de removido, o ouvinte de evento nunca mais é chamado novamente (a menos que registrado mais uma vez para processamento futuro).

Parâmetros

	`type:String` — O tipo de evento.

	`listener:Function` — A função de ouvinte que processa o evento. Esta função deve aceitar um objeto Event como seu único parâmetro e não deve retornar nada, como mostra este exemplo: function(evt:Event):void A função pode ter qualquer nome.

	`useCapture:Boolean` (default = `false`) — Determina se o ouvinte trabalha na fase de captura ou nas fases de destino e bubbling. Se `useCapture` for definido como `true`, o ouvinte processará o evento apenas durante a fase de captura e não na fase de destino nem de bubbling. Se `useCapture` for `false`, o ouvinte processará o evento apenas durante a fase de destino ou de bubbling. Para ouvir o evento em todas as três fases, chame o `addEventListener` duas vezes, uma vez com o `useCapture` definido como `true`, e novamente, com o `useCapture` definido como `false`.

	`priority:int` (default = `0`) — O nível de prioridade do ouvinte de evento. A prioridade é designada por um número inteiro de 32 bits sem sinal. Quanto mais alto o número, maior a prioridade. Todos os ouvintes com prioridade n são processados antes dos ouvintes com prioridade n-1. Se dois ou mais ouvintes compartilham a mesma prioridade, eles são processados pela ordem segundo a qual foram adicionados. A prioridade padrão é 0.

	`useWeakReference:Boolean` (default = `false`) — Determina se a referência ao ouvinte é forte ou fraca. Uma referência forte (a padrão) impede que o ouvinte seja coletado como lixo. Uma referência fraca não impede. Funções de membro de nível de classe não estão sujeitas à coleta de lixo, portanto, você pode definir `useWeakReference` como `true` para funções de membro de nível de classe sem sujeitá-las à coleta de lixo. Se você definir `useWeakReference` como `true` para um ouvinte que seja uma função interna aninhada, a função será sujeita à coleta de lixo e não mais será persistente. Se você criar referências à função interna (salve-a em outra variável), então ela não ficará sujeita à coleta de lixo e permanece persistente.

close

()

método

public function close():void

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Instrui o MessageChannel atual para ser fechado depois que todas as mensagens forem recebidas.

Quando efetuar uma chamada a este método, não será possível efetuar chamadas ao método send() para adicionar mensagens à fila. A chamada send() apresentará falha e retornará o valor false.

Você também poderá apenas efetuar chamadas ao método receive() para receber mensagens que já estão em espera na fila. Se a fila estiver vazia, a chamada receive() retornará o valor null.

Eventos

channelState:Event — enviado quando o método close() é chamado (o que define a propriedade state para MessageChannelState.CLOSING). Enviado novamente quando todas as mensagens foram recebidas e a propriedade state estiver definida para MessageChannelState.CLOSED.

receive

()

método

public function receive(blockUntilReceived:Boolean = false):*

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Recupera um objeto de mensagem único da fila de mensagens enviado através deste canal de mensagens.

Cada vez que o código do worker de envio fizer uma chamada ao método send() do objeto MessageChannel, um único objeto será adicionado à fila de mensagens interna do canal de mensagem. Estes objetos ficam empilhados na fila até que sejam removidos um de cada vez, pelo worker de destino chamando o método receive(). Os objetos de mensagem são recebidos na ordem em que são enviados.

Para verificar se a fila contém um objeto de mensagem a ser recebido, utilize a propriedade messageAvailable.

Nos casos comuns, o objeto transformado em send() é transformado em uma série de formato AMF3. Quando é removido da fila pela chamada receive() é removido da série e transformado em um objeto ActionScript (uma cópia do objeto original) no worker de destino e o worker recebe uma referência àquela cópia. Certos tipos de objetos são compartilhados entre workers em vez de copiados. Neste caso, o objeto obtido pelo worker de destino é uma referencia ao objeto compartilhado, em vez de uma nova cópia do objeto. Para obter mais informações sobre este caso, consulte a descrição do método send().

O comportamento do método pode ser alterado se a fila de mensagem estiver vazia e você transmitir true ao parâmetro blockUntilReceived. Neste caso, o worker pausa seu thread de execução na chamada receive() e não executa mais códigos. Quando o worker de envio efetuar uma chamada ao send(), a chamada ao receive() será concluída ao receber a mensagem. O worker, então, retoma a execução do código na próxima linha do código seguindo a chamada recebida.

Parâmetros

blockUntilReceived:Boolean (default = false) — indica se o thread de execução do worker deve receber um objeto de mensagem e, então, continuar a execução (false) ou se deve pausar na chamada receive() e esperar que a mensagem seja enviada se a fila estiver vazia (true)

Retorna

* — uma cópia do objeto transformado no método send() pelo worker de envio. Se o objeto for um dos tipos especiais compartilhados entre os workers, o valor retornado será uma referência ao objeto compartilhado, em vez de uma cópia dele. Se nenhuma mensagem estiver disponível na fila, o método retornará null.

Lança

	`IOError` — se o canal estiver fechado no momento em que o método for chamado ou se o argumento `blockUntilReceived` resultar em uma execução sendo pausada e o canal for, então, fechado por outro worker.

	`ArgumentError` — se o código de chamada não estiver no worker de destino

	`ScriptTimeoutError` — se o método for chamado a partir do código no worker primário no Flash Player e o argumento `blockUntilReceived` fizer com que o worker seja pausado por mais tempo que o limite de tempo do script (15 segundos por padrão)

Elementos da API relacionados

método send()
Propriedade messageAvailable

removeEventListener

()

método

override public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Remove um ouvinte do objeto EventDispatcher. Se não existir um ouvinte correspondente registrado com o objeto EventDispatcher, uma chamada para esse método não terá efeito.

Parâmetros

	`type:String` — O tipo de evento.

	`listener:Function` — O objeto de ouvinte a remover.

	`useCapture:Boolean` (default = `false`) — Especifica se o ouvinte foi registrado na fase de captura ou nas fases de destino e bubbling. Se o ouvinte foi registrado para as fases de destino e de bubbling, duas chamadas para o `removeEventListener()` serão necessárias para remover as duas, uma chamada com o `useCapture()` definido como `true` e outra chamada com o `useCapture()` definido como `false`.

send

()

método

public function send(arg:*, queueLimit:int = -1):void

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Envia um objeto a partir do worker de envio, adicionando-o à fila da mensagem ao worker de destino.

O objeto passou ao parâmetro arg pode ser qualquer objeto. Diferentemente das exceções descritas abaixo, qualquer objeto transmitido ao parâmetro arg não é transmitido por referência. Qualquer alteração feita no objeto em um worker após a chamada ao send() não é transportada ao outro worker. O objeto é copiado quando é criado em série ao formato AMF3 e removido da série em um novo objeto, no worker de destino quando o receive() é chamado. Por este motivo, qualquer objeto que puder ser criado em série em um formato AMF3, incluindo os objetos em exibição, não podem ser transmitidos ao parâmetro arg. Para transmitir de forma adequada uma classe personalizada, a definição da classe pode ser registrada usando a função flash.net.registerClassAlias() ou o metadado [RemoteClass]. Com tais técnicas, o mesmo alias pode ser usado para ambas as versões do worker da classe.

Há cinco tipos de objetos que uma exceção à regra de que os objetos não são compartilhados entre os workers:

O trabalhador
MessageChannel
ByteArray compartilhável (um objeto ByteArray com a propriedade shareable definida como true
Mutex
Condição

Se você transmitir uma instância destes objetos ao parâmetro arg, cada worker terá uma referência ao mesmo objeto adjacente. As alterações feitas a uma instância em um worker são imediatamente disponíveis em outros workers. Além disso, se você transportar a mesma instância desses objetos mais de uma vez usando send(), o runtime não criará uma nova cópia do objeto no worker de destino. Em vez disso, a mesma referência é reutilizada, reduzindo o uso da memória do sistema.

Por padrão, este método adiciona o objeto à fila e imediatamente retorna, continuando em execução com a próxima linha de código. Se você deseja impedir que a fila cresça além de determinado tamanho, você pode usar o parâmetro queueLimit para especificar o número máximo de itens permitidos na fila. Se, no momento da chamada ao send(), o número de itens na fila é superior ao limite especificado, o worker pausa o thread de execução na chamada ao send(). Quando o worker de destino chamar receive() uma quantidade de vezes suficiente para que o tamanho da fila seja inferior ao limite da fila especificado, a chamada ao send() será concluída. O worker, então, continua a execução na próxima linha do código.

Parâmetros

	`arg:*` — o objeto a ser adicionado à fila da mensagem

	`queueLimit:int` (default = `-1`) — o número máximo de objetos de mensagem que a fila de mensagem pode conter. Se a fila contiver mais objetos que o limite permitido, o worker de envio pausa a execução até que as mensagens sejam recebidas e o tamanho da fila diminui para abaixo do seu limite.

Eventos

channelMessage:Event — enviado para notificar o worker de destino que um objeto de mensagem está disponível na fila

Lança

	`IOError` — se o canal estiver fechado no momento em que o método for chamado ou se o argumento `queueLimit` resultar em uma execução sendo pausada e o canal for, então, fechado por outro worker.

	`ArgumentError` — se o código de chamada não estiver no worker de envio

	`ScriptTimeoutError` — se o método for chamado a partir do código no worker primário no Flash Player e o argumento `queueLimit` fizer com que o worker seja pausado por mais tempo que o limite de tempo do script (15 segundos por padrão)

Elementos da API relacionados

Método receive()
Classe Worker
Propriedade ByteArray.shareable
Classe Mutex
Classe Condition

toString

()

método

override public function toString():String

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Retorna a representação de string do objeto especificado.

Nota: os métodos da classe Object são dinamicamente criados no protótipo de Object. Para redefinir esse método em uma subclasse de Object, não use a palavra-chave override. Por exemplo, uma subclasse de Object implementa function toString():String em vez de usar uma substituição da classe base.

Retorna

String — Uma representação de string do objeto.

Detalhe do evento

channelMessage

Evento

Tipo do objeto de evento: flash.events.Event
propriedade Event.type = flash.events.Event.CHANNEL_MESSAGE

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Enviado cada vez que o worker de envio efetuar uma chamada a este método send() do objeto MessageChannel, indicando que um novo objeto de mensagem está disponível na fila da instância do MessgeChannel.

A constante Event.CHANNEL_MESSAGE define o valor da propriedade type de um objeto de evento channelMessage.

Esse evento tem as seguintes propriedades:

Propriedade	Valor
`bubbles`	`false`
`cancelable`	`false`; não há comportamento padrão a ser cancelado.
`currentTarget`	O objeto que está processando ativamente o objeto Event com um ouvinte de evento.
`target`	O objeto que despachou este evento.

channelState

Evento

Tipo do objeto de evento: flash.events.Event
propriedade Event.type = flash.events.Event.CHANNEL_STATE

Versão da linguagem:

ActionScript 3.0

Versões de runtime:

Flash Player 11.4, AIR 3.4

Enviado quando o valor da propriedade do estado do canal de mensagem é alterado.

A constante Event.CHANNEL_STATE define o valor da propriedade type de um objeto de evento channelState.

Esse evento tem as seguintes propriedades:

Propriedade	Valor
`bubbles`	`false`
`cancelable`	`false`; não há comportamento padrão a ser cancelado.
`currentTarget`	O objeto que está processando ativamente o objeto Event com um ouvinte de evento.
`target`	O objeto que despachou este evento.

Aspectos jurídicos | Política de privacidade on-line

MessageChannel - AS3

Pacotesx

Elementos de linguagem

Apêndices

Pacote flash.system

messageAvailable

state

addEventListener

close

receive

removeEventListener

send

toString

channelMessage

channelState