TsgcWebSocketHTTPServer › Événements › OnQueueDrained
Se déclenche lorsque la file d'attente sortante d'une connexion WebSocket passe de l'état non vide à l'état vide.
property OnQueueDrained: TsgcWSQueueDrainedEvent;
// TsgcWSQueueDrainedEvent = procedure(Connection: TsgcWSConnection) of object—
Ne se déclenche que lorsque la mise en file d'attente des messages est active pour la connexion concernée, c'est-à-dire lorsque QueueOptions.Text.Level, QueueOptions.Binary.Level ou QueueOptions.Ping.Level a une valeur autre que qmNone. Sans file d'attente, il n'y a rien à vider et l'événement n'est jamais déclenché. Les requêtes HTTP simples ne sont pas mises en file d'attente, seules les connexions WebSocket le déclenchent.
Le gestionnaire s'exécute en ligne sur le thread de connexion et n'est délibérément pas marshalé via NotifyEvents, contrairement à tous les autres événements de ce composant, il ne doit donc pas toucher à l'interface utilisateur. Cet écart est intentionnel. Tout l'intérêt de l'événement est qu'il s'exécute à ce point précis de la boucle de connexion, juste après que la file d'attente a été vidée et avant la lecture suivante, alors que le socket est encore inactif, de sorte que l'application peut distribuer le crédit suivant sans attendre. Le marshaler vers le thread principal détruirait cet avantage. Toute mise à jour d'une fiche, d'une grille ou d'un libellé doit être marshalée par l'application elle-même, avec TThread.Queue, TThread.Synchronize ou un message posté au thread principal.
Les exceptions levées à l'intérieur du gestionnaire sont interceptées et ignorées afin que la vidange se termine toujours. Un gestionnaire qui échoue le fait silencieusement, encadrez donc son corps dans son propre bloc try..except lorsqu'un échec doit être signalé.
L'événement se déclenche une fois par transition de l'état non vide vers l'état vide, et non une fois par passage de la boucle de connexion. Ce n'est pas un signal indiquant qu'une rafale est terminée. Si la vidange suit le rythme d'un producteur lent, chaque message peut déclencher son propre événement, car chaque message est écrit avant que le suivant ne soit mis en file d'attente. Ce que l'événement indique, c'est que la file d'attente de cette connexion est vide à cet instant, rien de plus.
L'usage typique est le contrôle de flux. Lorsque le serveur relaie des données en masse entre les clients, utilisez l'événement pour indiquer à un client émetteur qu'il peut en envoyer davantage. Associez-le à la propriété PendingCount de TsgcWSConnection, qui indique combien de messages sont encore en file d'attente pour cette connexion, afin de mettre en place une fenêtre de crédit plutôt qu'un échange en mode arrêt et attente.
Le portage .NET managé déclenche le même événement avec la même signification. La seule différence est la fréquence à laquelle il arrive. La vidange Delphi s'exécute une fois par passage de la boucle de connexion, soit toutes les Options.ReadTimeOut millisecondes, 10 par défaut, de sorte qu'un filet lent de messages est regroupé en peu d'événements. La vidange managée est pilotée par les événements et le même filet peut en déclencher davantage. Les rafales se comportent de façon identique dans les deux cas.
procedure OnQueueDrained(Connection: TsgcWSConnection);
begin
// runs on the connection thread, do not touch the user interface here
Connection.WriteData('credit 64');
end;