MessageChannel - Guida di riferimento alle API Adobe ActionScript® 3 (AS3 )

Pacchetto	flash.system
Classe	public final class MessageChannel
Ereditarietà	MessageChannel EventDispatcher Object

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

La classe MessageChannel fornisce un meccanismo che consente a un worker di comunicare con un altro worker. Un canale di messaggio è un canale di comunicazione a una sola via. Il worker mittente del canale di messaggio utilizza il canale per inviare oggetti al worker destinatario. Un oggetto MessageChannel è l’unico modo per inviare un messaggio tra worker che trasmette un evento per segnalare al destinatario che il messaggio è disponibile. Altri meccanismi per la condivisione dei dati consentono di impostare un valore ma non dispongono di un evento per segnalare che i dati sono cambiati.

Ogni oggetto MessageChannel contiene una coda di oggetti messaggio inviati dal worker mittente al worker destinatario. Ogni chiamata a send() aggiunge un oggetto alla coda. Ogni chiamata a receive() recupera l’oggetto messaggio più vecchio dalla coda.

Non è possibile creare istanze MessageChannel direttamente chiamando la funzione di costruzione MessageChannel(). Per creare un’istanza MessageChannel, chiamate il metodo createMessageChannel() dell’oggetto Worker che invierà i messaggi sul canale, passando come argomento l’oggetto Worker di destinazione.

Il flusso di lavoro tipico per l’invio di messaggi mediante un oggetto MessageChannel è il seguente:

Chiamate il metodo createMessageChannel() del worker mittente per creare il canale di messaggio

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

Passate il canale di messaggio all’altro worker, chiamando Worker.setSharedProperty() oppure inviandolo tramite un canale di messaggio già esistente
```
    receivingWorker.setSharedProperty("incomingChannel", sendChannel);
```

Il codice del worker destinatario registra un listener nell’oggetto MessageChannel per l’evento channelMessage

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

Il codice del worker mittente invia un messaggio chiamando il metodo send()

    // In the sending worker swf
    sendChannel.send("This is a message");

Il runtime chiama il gestore di eventi del codice del worker di destinazione, indicando che è stato inviato un messaggio

    // 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
    }

Il codice del worker destinatario chiama il metodo receive() per ricevere il messaggio. L’oggetto restituito dal metodo receive() ha lo stesso tipo di dati dell’oggetto passato al metodo send().
```
    var message:String = incomingChannel.receive() as String;
```

Oltre al flusso di lavoro asincrono appena descritto, potete usare un flusso di lavoro alternativo con il metodo receive() per mettere in pausa il codice nel worker destinatario e attendere l’invio di un messaggio. Per maggiori informazioni, vedete la descrizione del metodo receive().

La classe MessageChannel è uno dei tipi di oggetti speciali che vengono condivisi dai worker anziché copiati tra loro. Quando passate un canale di messaggio da un worker a un altro chiamando il metodo setSharedProperty() dell’oggetto Worker oppure utilizzando un oggetto MessageChannel, entrambi i worker hanno un riferimento allo stesso oggetto MessageChannel nella memoria del runtime.

Elementi API correlati

Classe Worker
Metodo Worker.createMessageChannel()

Proprietà pubbliche

Nascondi proprietà pubbliche ereditate

Mostra proprietà pubbliche ereditate

	Proprietà		Definito da
		constructor : Object Un riferimento all'oggetto classe o alla funzione di costruzione per una determinata istanza di oggetto.	Object
		messageAvailable : Boolean [sola lettura] Indica se il MessageChannel contiene uno o più messaggi del worker mittente nella propria coda messaggi interna.	MessageChannel
		state : String [sola lettura] Indica lo stato corrente dell’oggetto MessageChannel (aperto, in fase di chiusura o chiuso).	MessageChannel

Metodi pubblici

Nascondi metodi pubblici ereditati

Mostra metodi pubblici ereditati

	Metodo		Definito da
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void [override] Registra un oggetto listener di eventi con un oggetto EventDispatcher, in modo che il listener riceva la notifica di un evento.	MessageChannel
		close():void Indica al MessageChannel corrente di chiudere la comunicazione dopo che tutti i messaggi sono stati ricevuti.	MessageChannel
		dispatchEvent(event:Event):Boolean Invia un evento nel flusso di eventi.	EventDispatcher
		hasEventListener(type:String):Boolean Verifica se per l'oggetto EventDispatcher sono presenti listener registrati per un tipo specifico di evento.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indica se per un oggetto è definita una proprietà specifica.	Object
		isPrototypeOf(theClass:Object):Boolean Indica se un'istanza della classe Object si trova nella catena di prototipi dell'oggetto specificato come parametro.	Object
		propertyIsEnumerable(name:String):Boolean Indica se la proprietà specificata esiste ed è enumerabile.	Object
		receive(blockUntilReceived:Boolean = false):* Recupera un singolo oggetto messaggio dalla coda dei messaggi inviati tramite questo canale di messaggio.	MessageChannel
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void [override] Rimuove un listener dall'oggetto EventDispatcher.	MessageChannel
		send(arg:*, queueLimit:int = -1):void Invia un oggetto dal worker mittente, aggiungendolo alla coda messaggi del worker destinatario.	MessageChannel
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Imposta la disponibilità di una proprietà dinamica per le operazioni cicliche.	Object
		toLocaleString():String Restituisce la rappresentazione in formato stringa di questo oggetto, formattato in base alle convenzioni specifiche per le versioni localizzate.	Object
		toString():String [override] Restituisce la rappresentazione in formato stringa dell'oggetto specificato.	MessageChannel
		valueOf():Object Restituisce il valore di base dell'oggetto specificato.	Object
		willTrigger(type:String):Boolean Verifica se un listener di eventi è registrato con questo oggetto EventDispatcher o qualsiasi suo antenato per il tipo di evento specificato.	EventDispatcher

Eventi

Fate clic per visualizzare altre informazioni sugli eventi

Nascondi eventi ereditati

Mostra eventi ereditati

	Riepilogo	Definito da
activate	[evento di trasmissione] Inviato quando Flash Player o l'applicazione AIR ottiene lo stato di attivazione del sistema operativo ed entra nello stato attivo.	EventDispatcher
channelMessage	Inviato ogni volta che il worker mittente chiama il metodo send() di questo oggetto MessageChannel per indicare che è disponibile un nuovo oggetto messaggio nella coda dell’istanza MessageChannel.	MessageChannel
channelState	Inviato quando cambia il valore della proprietà state del canale di messaggio.	MessageChannel
deactivate	[evento di trasmissione] Inviato quando Flash Player o l'applicazione AIR perde l'attivazione del sistema operativo e sta entrando nello stato inattivo.	EventDispatcher

Descrizione delle proprietà

messageAvailable

proprietà

messageAvailable:Boolean [sola lettura]

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Indica se il MessageChannel contiene uno o più messaggi del worker mittente nella propria coda messaggi interna.

Implementazione
public function get messageAvailable():Boolean

state

proprietà

state:String [sola lettura]

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Indica lo stato corrente dell’oggetto MessageChannel (aperto, in fase di chiusura o chiuso). I valori possibili per questa proprietà sono definiti come costanti nella classe MessageChannelState.

Implementazione
public function get state():String

Elementi API correlati

Classe MessageChannelState

Descrizione dei metodi

addEventListener

()

metodo

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

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Registra un oggetto listener di eventi con un oggetto EventDispatcher, in modo che il listener riceva la notifica di un evento. Potete registrare listener di eventi in tutti i nodi dell'elenco di visualizzazione per un tipo di evento, una fase e una priorità specifiche.

Una volta registrato un listener di eventi, non potete modificarne la priorità mediante chiamate aggiuntive a addEventListener(). Per modificare la priorità di un listener dovete chiamare innanzitutto removeListener(). In seguito potete registrare nuovamente il listener con il nuovo livello di priorità.

Tenete presente che, dopo la registrazione del listener, le successive chiamate a addEventListener() con un valore type o useCapture diverso determinano la creazione di un'altra registrazione per il listener. Ad esempio, se registrate un listener inizialmente con useCapture impostato su true, l'intercettazione avviene solo durante la fase di cattura. Se chiamate di nuovo addEventListener() utilizzando lo stesso oggetto listener ma impostando useCapture su false, ottenete due listener separati: uno rileva gli eventi durante la fase di cattura e l'altro durante la fasi target e di bubbling.

Non potete registrare un listener di eventi solo per la fase target o per la fase di bubbling. Queste fasi vengono accoppiate durante la registrazione perché la propagazione è valida solo per gli antenati del nodo target.

Se il listener di eventi non è più necessario, rimovetelo con una chiamata a removeEventListener() per evitare problemi di memoria. I listener di eventi non vengono eliminati automaticamente dalla memoria perché il garbage collector non rimuove il listener fintantoché esiste l'oggetto che effettua l'invio (a meno che il parametro useWeakReference non sia impostato su true).

Se copiate un'istanza EventDispatcher, i listener di eventi associati all'istanza non vengono copiati (se un nodo appena creato necessita di un listener di eventi, dovete associarlo dopo avere creato il nodo). Se invece spostate un'istanza EventDispatcher, insieme a questa vengono spostati anche i listener di eventi associati.

Se il listener di eventi viene registrato su un nodo mentre questo sta elaborando un evento, il listener di eventi non viene attivato durante la fase corrente ma può esserlo durante una fase successiva del flusso di eventi, ad esempio la fase di bubbling.

Se un listener di eventi viene rimosso da un nodo mentre questo sta elaborando un evento, il listener continua a essere attivato dalle azioni in corso. Dopo che è stato rimosso, il listener di eventi non viene più richiamato (a meno che non venga registrato nuovamente per elaborazioni future).

Parametri

	`type:String` — Il tipo di evento.

	`listener:Function` — La funzione listener che elabora l'evento. Questa funzione deve accettare un oggetto Event come unico parametro e non restituire alcun valore, come mostra l'esempio che segue: function(evt:Event):void La funzione può avere qualunque nome.

	`useCapture:Boolean` (default = `false`) — Determina se il listener funziona nella fase di cattura o nelle fasi target e di bubbling. Se `useCapture` è impostato su `true`, il listener elabora l'evento solo durante la fase di cattura e non nella fase target o di bubbling. Se `useCapture` è impostato su `false`, il listener elabora l'evento solo durante la fase target o di bubbling. Per consentire l'intercettazione dell'evento in tutte e tre le fasi, chiamate due volte `addEventListener`, una volta con `useCapture` impostato su `true` e un'altra volta con `useCapture` impostato su `false`.

	`priority:int` (default = `0`) — Il livello di priorità del listener di eventi. La priorità è indicata da un numero intero a 32 bit con segno. Più alto è il numero, più alta è la priorità. Tutti i listener con priorità n vengono elaborati prima dei listener con priorità n-1. Se due o più listener hanno la stessa priorità, l'elaborazione avviene secondo l'ordine in cui sono stati aggiunti. La priorità predefinita è 0.

	`useWeakReference:Boolean` (default = `false`) — Determina se il riferimento al listener è forte o debole. Un riferimento forte (predefinito) evita che il listener venga sottoposto al processo di garbage collection, un riferimento debole no. Le funzioni dei membri a livello di classe non sono soggette a garbage collection, pertanto è possibile impostare `useWeakReference` su `true`. Se impostate `useWeakReference` su `true` per un listener che è una funzione nidificata, la funzione viene sottoposta a garbage collection e non è più persistente. Se create riferimenti alla funzione nidificata (salvandola in un'altra variabile), questa non viene sottoposta a garbage collection e rimane persistente.

close

()

metodo

public function close():void

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Indica al MessageChannel corrente di chiudere la comunicazione dopo che tutti i messaggi sono stati ricevuti.

Una volta chiamato questo metodo, non potete più chiamare il metodo send() per aggiungere messaggi alla coda. La chiamata send() fallisce e restituisce false.

Potete inoltre chiamare il metodo receive() per ricevere messaggi che sono già in attesa nella coda. Se la coda è vuota, la chiamata receive() restituisce null.

Eventi

channelState:Event — Inviato quando viene chiamato il metodo close() (che imposta la proprietà state su MessageChannelState.CLOSING). Inviato di nuovo quando tutti i messaggi sono stati ricevuti e la proprietà state è impostata su MessageChannelState.CLOSED.

receive

()

metodo

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

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Recupera un singolo oggetto messaggio dalla coda dei messaggi inviati tramite questo canale di messaggio.

Ogni volta che il worker mittente chiama il metodo send() dell’oggetto MessageChannel, un nuovo oggetto messaggio viene aggiunto alla coda messaggi interna del canale di messaggio. Questi oggetti vengono impilati nella coda finché non vengono rimossi uno alla volta dal worker destinatario chiamando il metodo receive(). Gli oggetti messaggio vengono ricevuti nell’ordine in cui sono stati inviati.

Per verificare se la coda contiene un oggetto messaggio da ricevere, utilizzate la proprietà messageAvailable.

Nel caso standard, l’oggetto passato in send() viene serializzato in formato AMF3. Quando viene rimosso dalla coda dalla chiamata receive(), viene deserializzato in un oggetto ActionScript (una copia dell’oggetto originale) nel worker destinatario e il worker riceve un riferimento a tale copia. Alcuni tipi di oggetti sono condivisi tra i worker anziché copiati. In questi casi, l’oggetto ricevuto dal worker destinatario è un riferimento all’oggetto condiviso anziché una nuova copia dell’oggetto. Per ulteriori informazioni su questo caso, vedete la descrizione del metodo send().

Il comportamento di questo metodo cambia se la coda messaggi è vuota e passate true nel parametro blockUntilReceived. In tal caso, il worker sospende il proprio thread di esecuzione a seguito della chiamata receive() e non esegue altro codice. Quando il worker mittente chiama send(), la chiamata receive() viene completata con la ricezione del messaggio. Il worker quindi riprende l’esecuzione del codice dalla prima riga di codice successiva alla chiamata di ricezione.

Parametri

blockUntilReceived:Boolean (default = false) — Indica se il thread di esecuzione del worker deve ricevere un oggetto messaggio e quindi continuare l’esecuzione (false) oppure se deve entrare in pausa al ricevimento della chiamata receive() e attendere l’invio di un messaggio se la coda è vuota (true).

Restituisce

* — Una copia dell’oggetto passato nel metodo send() dal worker mittente. Se l’oggetto è uno dei tipi speciali che sono condivisi tra i worker, il valore restituito è un riferimento all’oggetto condiviso anziché a una sua copia. Se nella coda non sono disponibili messaggi, il metodo restituisce null.

Genera

	`IOError` — Se il canale è chiuso nel momento in cui il metodo viene chiamato oppure se l’argomento `blockUntilReceived` determina una sospensione dell’esecuzione e il canale viene quindi chiuso da un altro worker.

	`ArgumentError` — Se il codice chiamante non è nel worker destinatario.

	`ScriptTimeoutError` — Se il metodo viene chiamato dal codice nel worker primordiale in Flash Player e l’argomento `blockUntilReceived` determina una sospensione del worker più lunga del limite di timeout dell script (durata predefinita 15 secondi).

Elementi API correlati

send(), metodo
Proprietà messageAvailable

removeEventListener

()

metodo

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

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Rimuove un listener dall'oggetto EventDispatcher. Se non esiste un listener corrispondente registrato nell'oggetto EventDispatcher, la chiamata a questo metodo non ha alcun effetto.

Parametri

	`type:String` — Il tipo di evento.

	`listener:Function` — L'oggetto listener da rimuovere.

	`useCapture:Boolean` (default = `false`) — Specifica se il listener è stato registrato per la fase di cattura o per le fasi target e di bubbling. Se il listener è stato registrato sia per la fase di cattura che per quelle target e di bubbling, per eliminarle entrambe sono necessarie due chiamate a `removeEventListener()`, una con `useCapture()` impostato su `true` e un'altra con `useCapture()` impostato su `false`.

send

()

metodo

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

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Invia un oggetto dal worker mittente, aggiungendolo alla coda messaggi del worker destinatario.

L’oggetto passato al parametro arg può essere quasi qualsiasi oggetto. Salvo le eccezioni indicate di seguito, qualunque oggetto passato al parametro arg non viene passato mediante un riferimento. Le modifiche apportate all’oggetto in un worker dopo la chiamata send() non vengono applicate all’altro worker. L’oggetto viene copiato serializzandolo in formato AMF3 e deserializzandolo in un nuovo oggetto nel worker destinatario quando viene chiamato receive(). Per questo motivo, qualsiasi oggetto che non può essere serializzato nel formato AMF3, compresi gli oggetti di visualizzazione, non può essere passato al parametro arg. Affinché una classe personalizzata possa essere passata correttamente, la definizione della classe deve essere registrata utilizzando la funzione flash.net.registerClassAlias() o il metadato [RemoteClass]. In ambedue i casi occorre utilizzare lo stesso alias per entrambe le versioni della classe destinate ai due worker.

Cinque tipi di oggetti rappresentano eccezioni alla regola che prevede che gli oggetti non possano essere condivisi tra i worker:

Il worker
MessageChannel
ByteArray condivisibile (un oggetto ByteArray con la proprietà shareable impostata su true).
Mutex
Condition

Se si passa un’istanza di questi oggetti al parametro arg, ogni worker ha un riferimento allo stesso oggetto sottostante. Le modifiche apportate a un’istanza in un worker sono immediatamente disponibili negli altri worker. Inoltre, se passate la stessa istanza di questi oggetti più di una volta utilizzando send(), il runtime non crea una nuova copia dell’oggetto nel worker destinatario. Viene invece riutilizzato lo stesso riferimento, riducendo così il consumo di memoria.

Per impostazione predefinita, questo metodo aggiunge l’oggetto alla coda e restituisce immediatamente il valore, proseguendo l’esecuzione dalla riga di codice successiva. Per impedire che la coda aumenti di dimensioni oltre un certo limite, potete usare il parametro queueLimit per specificare il numero massimo di elementi consentiti nella coda. Se nel momento in cui chiamate send() il numero di elementi nella coda è maggiore del limite impostato, il worker sospende il thread di esecuzione in corrispondenza della chiamata send(). Dopo che il worker destinatario avrà chiamato receive() per un numero di volte sufficiente a fare scendere la dimensione della coda sotto il limite specificato, la chiamata send() verrà completata. Il worker quindi riprende l’esecuzione dalla riga di codice successiva.

Parametri

	`arg:*` — L’oggetto da aggiungere alla coda messaggi.

	`queueLimit:int` (default = `-1`) — Il numero massimo di oggetti messaggio caratteri che la coda messaggi può contenere. Se la coda contiene più oggetti del limite, il worker mittente sospende l’esecuzione finché i messaggi non vengono ricevuti e il numero di messaggi coda non scende sotto il limite.

Eventi

channelMessage:Event — Inviato per notificare al worker destinatario che nella coda è disponibile un oggetto messaggio.

Genera

	`IOError` — Se il canale è chiuso nel momento in cui il metodo viene chiamato oppure se l’argomento `queueLimit` determina una sospensione dell’esecuzione e il canale viene quindi chiuso da un altro worker.

	`ArgumentError` — Se il codice chiamante non è nel worker mittente.

	`ScriptTimeoutError` — Se il metodo viene chiamato dal codice nel worker primordiale in Flash Player e l’argomento `queueLimit` determina una sospensione del worker più lunga del limite di timeout dell script (durata predefinita 15 secondi).

Elementi API correlati

Metodo receive()
Classe Worker
Proprietà ByteArray.shareable
Classe Mutex
Classe Condition

toString

()

metodo

override public function toString():String

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Restituisce la rappresentazione in formato stringa dell'oggetto specificato.

Nota: i metodi della classe Object vengono creati dinamicamente sul prototipo di Object. Per ridefinire questo metodo in una sottoclasse di Object, non utilizzate la parola chiave override. Ad esempio, una sottoclasse di Object implementa function toString():String anziché utilizzare un override della classe base.

Restituisce

String — La rappresentazione in formato stringa dell'oggetto.

Descrizione degli eventi

channelMessage

Evento

Tipo di oggetto evento: flash.events.Event
proprietà Event.type = flash.events.Event.CHANNEL_MESSAGE

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Inviato ogni volta che il worker mittente chiama il metodo send() di questo oggetto MessageChannel per indicare che è disponibile un nuovo oggetto messaggio nella coda dell’istanza MessageChannel.

La costante Event.CHANNEL_MESSAGE definisce il valore della proprietà type di un oggetto evento channelMessage.

Questo evento ha le seguenti proprietà:

Proprietà	Valore
`bubbles`	`false`
`cancelable`	`false`; non è presente alcun comportamento predefinito da annullare.
`currentTarget`	L'oggetto che elabora attivamente l'oggetto Event con un listener di eventi.
`target`	L'oggetto che ha inviato l'evento.

channelState

Evento

Tipo di oggetto evento: flash.events.Event
proprietà Event.type = flash.events.Event.CHANNEL_STATE

Versione linguaggio:

ActionScript 3.0

Versioni runtime:

Flash Player 11.4, AIR 3.4

Inviato quando cambia il valore della proprietà state del canale di messaggio.

La costante Event.CHANNEL_STATE definisce il valore della proprietà type di un oggetto evento channelState.

Questo evento ha le seguenti proprietà:

Proprietà	Valore
`bubbles`	`false`
`cancelable`	`false`; non è presente alcun comportamento predefinito da annullare.
`currentTarget`	L'oggetto che elabora attivamente l'oggetto Event con un listener di eventi.
`target`	L'oggetto che ha inviato l'evento.

Note legali | Informativa sulla privacy online

MessageChannel - AS3

Pacchettix

Elementi del linguaggio

Appendici

Pacchetto flash.system

messageAvailable

state

addEventListener

close

receive

removeEventListener

send

toString

channelMessage

channelState