TsgcWebSocketServer › Eventi › OnQueueDrained
Si attiva quando la coda in uscita di una connessione client passa dall'avere messaggi all'essere vuota.
property OnQueueDrained: TsgcWSQueueDrainedEvent;
// TsgcWSQueueDrainedEvent = procedure(Connection: TsgcWSConnection) of object—
Si attiva solo quando l'accodamento dei messaggi è attivo per la connessione interessata, cioè quando QueueOptions.Text.Level, QueueOptions.Binary.Level o QueueOptions.Ping.Level è impostato su un valore diverso da qmNone. Senza una coda non c'è nulla da svuotare e l'evento non viene mai generato.
Il gestore viene eseguito inline sul thread della connessione e deliberatamente non viene instradato attraverso NotifyEvents, a differenza di tutti gli altri eventi di questo componente, quindi non deve toccare l'interfaccia utente. La deviazione è intenzionale. Tutto il valore dell'evento sta nel fatto che viene eseguito esattamente in quel punto del ciclo della connessione, subito dopo che la coda si è svuotata e prima della lettura successiva, mentre il socket è ancora inattivo, in modo che l'applicazione possa concedere il credito successivo senza attendere. Instradarlo verso il thread principale distruggerebbe questo vantaggio. Qualsiasi aggiornamento di form, griglia o etichetta deve essere instradato dall'applicazione stessa, con TThread.Queue, TThread.Synchronize o un messaggio inviato al thread principale.
Le eccezioni generate all'interno del gestore vengono intercettate e scartate, in modo che lo svuotamento venga sempre completato. Un gestore che fallisce lo fa in silenzio, quindi racchiudere il corpo in un proprio blocco try..except quando un errore deve essere segnalato.
L'evento si attiva una volta per ogni transizione da coda non vuota a coda vuota, non una volta per ogni passaggio del ciclo della connessione. Non è un segnale che una raffica è terminata. Se lo svuotamento tiene il passo con un produttore lento, ogni singolo messaggio può generare il proprio evento, perché ciascun messaggio viene scritto prima che venga accodato il successivo. Ciò che l'evento afferma è che la coda di questa connessione è vuota in questo momento, nulla di più.
L'uso tipico è il controllo di flusso. Quando il server trasferisce dati di massa tra client, utilizzare l'evento per comunicare a un client mittente che può inviarne altri. Abbinarlo alla proprietà PendingCount di TsgcWSConnection, che indica quanti messaggi sono ancora accodati per quella connessione, per gestire una finestra di credito invece di uno scambio stop and wait.
Il port gestito .NET genera lo stesso evento con lo stesso significato. L'unica differenza è la frequenza con cui arriva. Lo svuotamento Delphi viene eseguito una volta per ogni passaggio del ciclo della connessione, cioè a distanza di Options.ReadTimeOut millisecondi, 10 per impostazione predefinita, quindi un flusso lento di messaggi viene raggruppato in pochi eventi. Lo svuotamento gestito è guidato dagli eventi e lo stesso flusso lento può generare più eventi. Le raffiche si comportano in modo identico in entrambi i casi.
procedure OnQueueDrained(Connection: TsgcWSConnection);
begin
// runs on the connection thread, do not touch the user interface here
Connection.WriteData('credit 64');
end;