docs/pws2006/event.pod

=head1 Ereignisgesteuerte Programmierung mit Perl - die Realität

=head2 Zusammenfassung

Ereignisgesteuerte Programmierung ist hinreichend bekannt. Trotzdem
wird sie relativ selten benutzt - in Modulen so gut wie garnicht. Ich
möchte hier verschiedene Arten der Ereignissteuerung sauber von anderen
Formen der Programmierung trennen, vorhandene Ereignismodule und ihre
Unterschiede vorstellen. Vor allem sollen Möglichkeiten gezeigt werden,
wie man als Modulautor - je nach gewünschtem Aufwand - verschiedene APIs
anbieten kann.


=head1 Ereignissteuerung - In aller Kürze

Ereignissteuerung ist - für mich - kein sehr exakt festgelegter Begriff
oder eine festgelegte Syntax. Daher will ich einige Beispiele für
verschiedene Arten bzw. Grade der Ereignissteuerung, wie sie in der Praxis
vorkommen, vorstellen.

Üblicherweise verwendet man Ereignissteuerung immer dann, wenn man
genügend Rechenzeit für die Verarbeitung vieler Aufgaben hat, jedoch durch
externe Umstände (I/O-Geschwindigkeit, Netzwerk, User klickt nicht schnell
genug :) gezwungen ist, auf Daten bzw. Ereignisse zu warten.

Ereignissteuerung bedeutet dann, ein Programm derart zu strukturieren,
daß es auf Ereignisse wartet und - möglichst schnell - reagiert. Die
Haupt-Eingabe besteht sozusagen in einem Strom von Ereignissen
(Event-Stream). Das Ziel der Ereignissteuerung ist es, die Gesamtdauer
aller Operationen zu verringern und die Reaktionsgeschwindigkeit zu
erhöhen.

Unter Unix gibt es eine zentrale Funktion, mit der ein Programm auf
Ereignisse warten kann: C<select> (bzw. auch C<pselect>/C<poll>, die sich
aber nicht von C<select> unterscheiden, sowie kompliziertere Methoden wie
realtime-Signale, die aber alle auf dasselbe hinauslaufen). C<select> kann
auf einen Timeout und auf die Möglichkeit, auf einen Filehandle schreiben
oder davon lesen zu können, warten. Dies reicht für alles aus, da unter
Unix "alles ein Dateihandle ist" (und wenn dies einmal nicht der Fall ist,
ist das gleich ein major pain in the ass und man tut gut daran, es auf
einen Dateihandle abzubilden).

Daher ist eine derartige Programmstruktur meist eine zentrale Schleife,
in der auf Ereignisse (definiert durch "Watcher") gewartet wird und
dann Funktionen aufgerufen werden, um auf diese Ereignisse zu reagieren
("Callbacks"). Da C<select> etwas low-level ist, gibt es Bibliotheken
und Module, die diese Funktionalität in eine freundlichere Schnittstelle
gießen - das nennt man dan "Event-Modell".

Daraus folgt, daß das "Hauptprogramm" der Aufruf dieser Schleife/dieses
Event-Modells ist, und alle Ereignisse in Unterfunktionen behandelt werden
müssen. Daher lassen sich in einem Programm auch sehr schwer mehrere
Event-Modelle miteinander mischen, da nur jeweils eines die Kontrolle über
den Programmablauf haben kann.


=head1 Formen der Ereignissteuerung

=head2 Linearer Ablauf - "Nicht ereignisgesteuert"

Wir alle kennen (hoffe ich) LWP, mit dem man sehr einfach Webseiten u.ä.
abrufen kann:

   use LWP::Simple;
   print get "http://www.cpan.org/";

Ein heutiger Rechner kann das in Millisekunden erledigen - wenn es länger
dauert, liegt es nicht am eigenen Rechner sondern am Netz. LWP arbeitet
intern nämlich folgendermaßen:

   $socket = new IO::Socket ...;
   print $socket $request;
   $response = read $socket;
   return $response;

Die Wartezeit entsteht vor allem beim Lesen der Antwort, zu kleineren
Teilen beim Verbindungsaufbau und selten beim Schreiben der Anforderung.

Prinzipiell gibt es auch hier eine Folge von Ereignissen, auf die gewartet
wird - allerdings immer nur eines, d.h. die Ereignisse "steuern" den
Programmablauf nicht. Daher ist dies keine Ereignissteuerung.

Der Vorteil einer solchen Struktur ist ihre Einfachheit - die zeitliche
und logische Abfolge des Requests stehen klar hintereinander.

Diese Einfachheit läßt sich auch ereignisgesteuert erreichen - allerdings
mit beträchtlichem Mehraufwand an anderer Stelle, den man jedoch gut in
andere Module verpacken kann.

=head3 blocking vs. "blocking"

Ein paar Worte noch zu blocking vs. non-blocking, bzw. blocking vs.
andere Arten von blocking: Unter Unix kann man Filehandles in den
"non-blocking"-Zustand versetzen. Dies ist manchmal hilfreich, hat aber
mit Ereignissteuerung wenig zu tun:  Zum Lesen von Sockets braucht man
dies nicht, und bei Dateien zeigt es keine Wirkung (es wirkt nur auf
Dateihandles, bei denen die Menge an Daten unbekannt ist). In vielen
Fällen ist es sogar hinderlich.

So ist es bei vielen Protokollen (whois, finger, viele HTTP-Anfragen)
fast sicher, daß die Anfrage komplett in den TCP-Buffer geschrieben
werden kann. Passt er nicht, blockiert der Prozess, aber wenn dies
unter normalen Umständen nicht vorkommt, ist dies meistens akzeptabler
als die Programmstruktur nur für diesen zu verkomplizieren, wie dies
bei einem non-blocking Dateihandle nötig wäre (leider erzeugt das
C<IO::Socket>-Modul alle Socket-Handles per default non-blocking, was
meiner Meinung nach mehr Probleme schafft als löst).

In diesem Dokument wird der Begriff "blockierend" nicht als Gegensatz zu
diesem C<O_NONBLOCK> gebraucht, sondern allgemein verwendet, um jeglichen
Aufruf zu beschreiben, der auf bestimmte Ereignisse warten muss, statt
sofort zurückzukehren. Dies schließt nicht nur Dinge wie das Lesen von
Sockets, wenn keine Daten vorhanden sind, oder sleep()-ähnliche Aufrufe ein,
sondern auch Dinge wie das Lesen von einer Datei auf der Festplatte oder
von NFS, wenn die Daten nicht im RAM sind.

=head2 State-Maschinen

Um nun auf Ereignisse in beliebiger Folge reagieren zu können, muss man
jedes Ereignis ("Verbindung aufgebaut", "Daten können geschrieben werden",
"Daten können gelesen werden") in einer Unterroutine abarbeiten.

Bei Frameworks wie POE werden alle diese Unterroutinen als Methoden eines
Objektes aufgefasst. Das Objekt speichert den Zustand (z.B. "Aufbauphase",
"Antwortphase"). Bei jedem Ereignis muss der Zustand aus dem Objekt
"deserialisiert" werden, die Methode aufgerufen werden und der neue
Zustand wieder serialisiert werden.

Für das Finger-Protokoll würde das in etwa so aussehen (völlig fiktive
Syntax):

   # wird aufgerufen, wenn Daten geschrieben werden können
   sub can_write {
      my ($self) = @_;

      # Request blockierend schreiben, da klein
      print {$self->{fh}} $self->{username};
      # sorge dafür, daß beim nächsten Mal can_read aufgerufen wird
      $self->next_event ($self->{fh}, "readable", "can_read");
   }

   # wird aufgerufen, wenn Daten vorliegen
   sub can_read {
      my ($self) = q_;

      sysread $self->{fh}, $self->{response}, length $self->{response}, 8192
         or $self->next_event (undef, undef, "finish");
   }

C<can_write> schreibt den Request und sorgt dann dafür, daß der Zustand
"can_read" angenommen wird, bei dem die Methode desselben Namens aufgerufen
wird, sobald Daten vom Dateihandle gelesen werden können.

C<can_read> liest nun die Daten ein und verbleibt im aktuellen Zustand,
solange Daten gelesen werden können. Bei Fehlern oder bei Verbindungsende
wird in den Zustand "finish" gesprungen. Typischerweise gibt es noch
andere Methoden, die z.B. bei Fehlern aufgerufen werden können.

Persönlich finde ich diesen Stil äußerst masochistisch und verwirrend,
aber es soll Programmierer geben, die anders denken. Für mich zählt aber
vor allem die Menge an Quellcode, die erzeugt und gewartet werden muss,
sowie das weite Auseinanderliegen wichtiger Stellen - der Ablauf ist nicht
klar.

Trotzdem ist dieser Stil häufig vertreten - meistens nicht in dieser
Klarheit sondern in Kombination mit anderen Stilen (im obigen Beispiel
wird z.B. die Anfrage nicht ereignisgesteuert geschrieben) - in der
Realität muss man zwischen Klarheit, Geschwindigkeit, Abhängigkeiten und
vielem mehr abwägen!

=head2 Continuation Passing

Ein etwas weniger häufig benutzter Stil ist Continuation Passing. Die
Ursache für das seltenere Vorkommen liegt I<meiner Meinung> nach darin,
daß dies in anderen (verbreiteten) Programmiersprachen (C, Python, ...)
weniger oder garnicht gut realisierbar ist, bzw. dies etwas Verständnis
und Wissen erfordert, was heutzutage nicht mehr gefördert wird.

Wie dem auch sei, hier ein Beispiel wie man eine Datei öffnet und einige
Daten liest, und sie dann löscht, mit C<IO::AIO> und voller Fehlerbehandlung:

   aio_open "tempfile", O_RDONLY, 0, sub {
      my $fh = shift
         or die "tempfile: $!";

      my $buf;
      aio_read $fh, 0, 8192, $buf, 0, sub {
         $_[0] > 0 # keine leeren Files
            or die "tempfile: $!";

         aio_unlink "tempfile", sub {
            $_[0] and die "tempfile: $!";

            print "read successfully up to 8192 bytes, and nuked file.\n";
         };
      };
   };

Das Schema ist immer das gleiche: Bei jeder Anforderung (open/read/unlink)
wird eine Closure übergeben (die Zustandsdaten und Reaktion verkörpert),
die nach Beendigung der Anforderung aufgerufen wird. C<aio_open> kehrt
sofort zurück, aber die Closure wird erst dann aufgerufen, wenn die Datei
geöffnet wurde oder ein Fehler auftrat.

Der Name dieses Stils kommt daher, daß bei jeder Anforderung die komplette
"Fortsetzung" (Continuation) des Programmablaufes mit übergeben wird.

Die Vorteile des Stils liegen darin, daß die logische (nicht zeitliche)
lineare Reihenfolge klar bleibt und daß alles nahe beieinander
steht. Die Nachteile sind das zunehmende Nesting und die weniger flexiblen
Reaktionsmöglichkeiten. Außerdem bietet sich nicht jede Art der
Anforderung gleichermaßen an: C<IO::AIO> fördert diesen Stil. Bei C<Event> wird
es meistens etwas umständlicher, da mehr Parameter zu übergeben sind und
die Watcher nach jedem Ereignis per Hand gelöscht werden müssen.

Beides läßt sich umgehen, indem man sich in Richtung State-Maschine
bewegt:

   sub do_open {
      aio_open ..., sub {
         do_read (@_);
      };
   }

   sub do_read {
      my ($fh) = @_;

      aio_read ..., sub {
         do_unlink ($fh, @_);
      };
   }

   sub do_unlink {
      ...
   }

Das ist erstmal umständlicher, aber sehr langen Closures manchmal
vorzuziehen.  Der Zustand wird hier nicht in einem Objekt gespeichert,
sondern in den Closures (z.B. C<$fh> bei C<aio_read>).

=head2 Coroutinen/Threads/Prozesse

Der letzte Stil besteht darin, für jeden logischen Ablauf eine Coroutine,
einen Thread oder einen Prozess zu benutzen. Die Nachteile nenne ich
gleich: Coroutinen sind nicht in Perl integriert und daher etwas
unportabler als Perl selbst, Threads stehen in Perl überhaupt nicht zur
Verfügung, und Prozesse sind relativ große Dinger, von denen man sich
nicht wirklich viele halten möchte.

Das obige C<IO::AIO>-Beispiel sähe mit Hilfe von C<Coro::AIO> so aus:

   my $fh = aio_open "tempfile", O_RDONLY, 0
     or die "tempfile: $!";
   aio_read $fh, 0, 8192, my $buf, 0
      or die "tempfile empty or read error ($!)";
   aio_unlink "tempfile";

Meiner Meinung nach ist dies die klarste Methode, komplett
ereignisgesteuerte Abläufe darzustellen. Der Overhead, der durch die
Verwaltung von Coroutinen entsteht, ist allerdings höher als der anderer
Ansätze (allerdings niedriger als bei Threads oder Prozesse), und stellt
daher das andere Ende des Overhead vs. Einfachheit-Gegensatzes dar.


=head1 Event-Modelle

Perl strotzt geradezu vor Event-Modellen. Das ist keine gute Nachricht, da
sie alle inkompatibel sind.

Entstanden ist diese Situation dadurch, daß C<select> zwar prinzipiell
alles ermöglicht, aber nicht sehr freundlich ist. Daher entstand schnell
der Wunsch nach Wrapper und angenehmeren Schnittstellen. Vor allem
GUI-Toolkits bringen im allgemeinen ein eigenes Event-Modell mit, da hier
der Bedarf nach Ereignissteuerung besonders hoch ist, um die Latenz für
Benutzerinteraktionen niedrig zu halten.

Leider wird dies meistens nebensächlich behandelt - Gtk+/Glib z.B. hat ein
sehr umständliches Event-Modell, daß sich auch nicht durch Exaktheit z.B.
bei Timern hervortut.

Im folgenden will ich einige Event-Modelle kurz ansprechen:

=head2 Event

Das "Standard"-Eventmodul von Perl. Sollte es zumindest sein. Es bietet
mit Abstand die vernünftigste API! (!!) (!!!) (Wirklich!)

Die beiden wichtigsten Ereignisse, auf die ein Event-Modell reagieren
können muss, sind IO-Ready-Ereignisse (Daten können gelesen/geschrieben
werden) und Timer (Zeitsteuerung). Außerdem braucht man noch eine
Schnittstelle für die Hauptschleife.

Mit Event sieht dies so aus:

   # Auf Daten warten:
   Event->io (fd => $fh, poll => 'r', cb => sub {
      # es kann nichtblockierend gelesen werden
   });

   # Jede Stunde was tun:
   Event->timer (after => 3600, interval => 3600, cb => sub {
      # tue was
   });

   # Hauptschleife:
   Event::loop;

Leider ist die Entwicklung des Event-Modules eingeschlafen - es ist zwar
stabil und hat keine bekannten/relevanten Fehler, aber Patches z.B. für
die Unterstützung (in bestimmten Situationen) besser skalierender
Betriebssystem-Schnittstellen als C<select> wandern nicht oder nur halb in
die Distribution.

Dennoch stellt Event nahezu das Optimum dar.

=head2 Glib (Gtk2)

Glib implementiert das Event-Modell für Gtk+, sowie noch vieles weiteres,
wie z.B. Datentypen und Klassen (was die Unterstützung für Skript-Sprachen
so angenehm macht).

Die drei Beispiele lauten in Glib-Lingo so:

   # Auf Daten warten:
   add_watch Glib::IO fileno $fh, ['in', 'hup'], sub {
      # es kann nichtblockierend gelesen werden

      1 # wir wollen weitere Ereignisse dieser Art
   };

   # Jede Stunde was tun:
   add Glib::Timeout 3600_000, sub {
      # tue was

      1 # auch nächste Stunde sind wir wieder für Sie da
   };

   # Hauptschleife:
   1 while Glib::MainContext->default->iteration (1);

   # bzw.in Gtk2-Programmen:
   main Gtk2;

Interessanterweise erlaubt es Glib, die eigentliche C<select> (bzw.
hier: C<poll>) Funktion durch eine eigene zu ersetzen, was z.B. das
C<Glib::Event>-Modul ausnutzt.

=head2 Tk

Tk ist das traurigste Beispiel für ein Event-Modell: entweder etwas
ist nicht implementiert, oder es ist kaputt. Dennoch lassen sich die
wichtigsten Ereignisse mit Einschränkungen abbilden:

   # Richtig, wir brauchen tatsächlich ein Fenster!
   $mw = new MainWindow; # Namespace-Invasion
   withdraw $mw; # Flickerflacker

   # Auf Daten warten, nur ein watcher per filehandle
   $mw->fileevent ($fh, readable => sub {
      # es kann nichtblockierend gelesen werden
   });

   # _Ungefähr_ jede Stunde was tun
   my $cb; $cb = sub {
      # tue was

      $mw->after (3600_000, $cb);
   };
   $mw->after (3600_000, $cb);

   # Hauptschleife:
   Tk::MainLoop;

An Tk sieht man deutlich, daß die Priorität eines Windowing-Toolkits eben
beim Windowing liegt, und nicht in der Event-API.

=head2 Qt

Besitzt jemand Informationen zu Qt? Perl+Qt scheint mir ziemlich tot zu
sein...


=head1 Das Problem für Modulautoren

Das Problem für Modulautoren ist ganz einfach: Das Hauptprogramm kann
immer nur ein Event-Modell gleichzeitig benutzen. Benutzt man in seinem
Modul das gleiche, ist man fein raus, benutzt man ein anderes, geht es
nicht. Garnicht.

Also versuchen es viele Modul-Autoren garnicht erst und bieten nur eine
nicht ereignisgesteuerte Schnittstelle an - benutzt man LWP in einem
Gtk+-Programm, hängt es, bis die Daten da sind - nicht gerade toll.


=head1 Lösungen/Workarounds

Welche Lösungen und Workarounds gibt es für dieses Problem?

=head2 Wozu? Blocking reicht - LWP

Naja, dies ist kein Workaround, aber wie gesagt die Norm unter den
vorhanden Modulen (wobei das keine Ausrede ist, um nicht wenigstens ein
Modell wie z.B. Event zu unterstützen...).

LWP ist dabei nur ein Beispiel:

   my $data = get $url;

So sieht es auch bei fast allen Net::*-Modulen aus. Es gibt Workarounds
(technisch ausgedrückt "böse Hacks"), um auch solche Module zu zwingen,
aber sie sind bestenfalls nicht schön, und schlimmstenfalls kaputt, wenn
die zugrundeliegende Bibliothek globale Variablen auf mit Parallelität
nicht vereinbarer Weise benutzt - man müsste reinschauen können. Solche
Workarounds können meistens nur im Hauptprogramm eingesetzt werden.

=head2 Überlass es dem User - KGS::Protocol

Dies ist eine weitere, praktikable Möglichkeit, an das Problem
heranzutreten, ein Beispiel dafür ist das (völlig unbedeutende)
KGS::Protocol-Modul:

   my $socket = new IO::Socket::INET ... # blockierender connect
   $socket->blocking (0); # seufz

   my $conn = new KGS::Protocol;

   ...

   Event->io (fd => $socket, poll => 'r', cb => sub {
      sysread $socket, my $buffer, 8192;

      $conn->feed_data ($buffer);
   });

Das C<KGS::Protocol>-Modul weiss recht wenig über Sockets oder über
Dateihandles - das bleibt dem Benutzer des Moduls überlassen. Dieser
muss irgendwie (z.B. mit C<Event>) die Daten beschaffen und sie mit
C<feed_data> an das Modul übergeben.

Schreiben geschieht immer noch blockierend, was bei C<KGS::Protocol> in
der Praxis keine Relevanz hat. Das Modul läßt sich auch ohne Dateihandles
betreiben, was z.B. für Replays von aufgezeichneten Protokollen benutzt
werden kann - in seltenen Fällen ist das extrem hilfreich.

Ein anderes Modul, C<Net::Knuddels>, erlaubt diese Freiheit nicht,
hat aber dafür eine einfachere API. C<Net::Knuddels> braucht zwei
Ereignistypen: Eine Verzögerung um Flooding zu vermeiden und das "Daten
können gelesen werden"-Ereignis.

Das sieht dann so aus:

   $client = new Net::Knuddels::Client
      PeerAddr => "213.61.5.150:2710",
      command_wait => sub {
         my ($client, $wait) = @_;
         Event->timer (after => $wait, cb => sub { $client->command_cb });
      };

   Event->io (
      fd   => $client->fh,  
      poll => 'r',
      cb   => sub { 
         $client->ready
            or $_[0]->w->cancel;
   });

Mit C<command_wait> übergibt man einen Callback, der nach einer bestimmten
Zeit (C<$wait>) die C<command_cb>-Methode aufrufen soll. Wie er das
macht, ist relativ wurscht. Die Default-Implementation des Moduls
schläft einfach die entsprechende Zeit und ruft dann direkt die
C<command_cb>-Methode auf. Im obigen Beispiel wird ein Time-Watcher
erzeugt, der C<command_cb> aufruft, und kehrt dann sofort zurück.

Diese Methode funktioniert, weil das Problem garnicht erst gelöst
wird: Es wird lediglich zum Aufrufer hin verlagert. Ist der Aufrufer
das Hauptprogramm, muss es Event-Watcher erzeugen, ist der Aufrufer ein
anderes Modul, hat dies wieder das gleiche Problem - entweder legt es ein
Event-Modell fest oder er schiebt es wieder zu seinem Aufrufer.

Hierbei muss der Aufrufer entsprechend aufgeklärt werden, was die API
etwas verkompliziert.

=head2 Leg dich fest - Coro::Event

Eine weitere Methode ist es, sich festzulegen. Das Coro-Modul benötigte
dringend Events, und hat sich auf das Event-Modul eingeschossen (hey, es
ist der Standard...). C<Coro::Event> ist daher recht effizient und einfach
zu benutzen (nahezu gleiche API wie C<Event> selbst), unterstützt aber
(zur Zeit) auch nur das Event-Modul.

Das ist nicht unbedingt schlimmer als nur eine blockierende API
anzubieten, da man schlimmstenfalls immer eine blockierende API erstellen
kann - so laufen alle Coro::Event-Benutzer untereinander ereignisgesteuert,
aber z.B. ein Glib-Benutzer wird blockiert.

=head2 Bilde ein Modell auf ein anderes ab - Glib::Event

Manchmal hat man Glück und benutzt zwei Event-Modelle, die man mit Gewalt
kombinieren kann. Eine häufige Kombination ist Gtk2 (also Glib) zusammen
mit Event. Und die Lösung lautet C<Glib::Event>:

   use Gtk2 -init;
   use Glib::Event;

Jetzt kann man beliebige Module benutzen, die selbst Event benutzen, oder
direkt Event benutzen, wenn einem dessen API mehr zusagt:

   use Event;

   Event->timer (after => 1, interval => 1, cb => sub { ... });

   main Gtk2;

Tatsächlich funktioniert C<Glib::Event> sogar unabhängig vom Glib-Modul mit
jedem Programm, daß selbst die libglib benutzt und Perl z.B. einbettet.

C<Glib::Event> bringt die libglib dazu, intern Event zu benutzen. Das
macht aus Glib noch keinen Event-Benutzer (man muss immer noch die
Glib-Hauptschleife aufrufen, C<Event::loop> funktioniert nicht), begrenzt
das Problem aber immerhin auf den Aufruf der Hauptschleife, der nur einmal
pro Programm vorkommt.

Tatsächlich kann man sich mit Coroutinen behelfen, indem man die
Gtk+-Hauptschleife in eine Coroutine verlagert:

   use Gtk2 -init;
   use Coro;
   use Coro::Event;
   use Glib::Event;
   async { main Gtk2 };
   # tue andere Dinge
   Event::loop;

=head2 Threads (?) und Prozesse

Threads würden ebenfalls helfen, da man zumindest theoretisch jedes
Event-Modell in seinem eigenen Thread laufen lassen könnte. Leider nur
theoretisch, da die meisten Event-Modelle damit nicht klarkommen, und
Threads von Perl sowieso nicht unterstützt werden (der irrige Begriff
"Thread" bezeichnet in Perl eine Prozessemulation auf Thread-Basis, der
eingeführt wurde, um die extrem langsame Prozess-Erzeugung unter Windows
zu beschleunigen und später aus nicht nachvollziehbaren Gründen auf Unix
portiert wurde.  Perl-"Threads" vereinigen die Nachteile von Prozessen und
Threads mit extrem hohem Overhead ohne die jeweiligen Vorteile zu bieten).

Bleiben also nur separate Prozesse, was nicht sehr angenehm ist, aber in
vielen Fällen durchaus gangbar. Z.B. kann man LWP auf diese Weise begrenzt
parallelisieren:

   # Warnung: keine Fehlerbehandlung
   if (open my $subproc, "-|") {
      Event->io (fd => $subproc, poll => 'r', cb => sub {
         local $/;
         my $webpage = <$subproc>;
      });
   } else {
      print get $url;
   }

Mit Perl-Threads gestaltet es sich etwas umständlicher und vor allem
wesentlich ressourcenintensiver (außer unter Windows, wo Prozesse sowieso
mit Threads emuliert werden und der Aufwand daher gleich (und gleich
I<hoch>) ist).

=head2 AnyEvent

Ein relativ neues Modul ist C<AnyEvent>. Der Name ist angelehnt
an C<AnyDBM_File>, da es wie dieses Modul versucht, eine
implementationsunabhängige API zu liefern.

AnyEvent ist also kein eigenes Event-Modell, sondern nur eine
Schnittstelle zu einem existierenden. Der Vorteil für Modul-Autoren
ist nun, daß sie AnyEvent als Event-Modell benutzen können, sich aber
gleichzeitig sicher sein können, daß ihr Modul mit Event, Gtk+, Tk oder
sogar rxvt-unicode zusammenarbeiten. Das Modul ist erweiterbar, so daß
jede weitere Implementation automatisch mit vorhandenen Modulen läuft.

Natürlich kann AnyEvent nur das unterstützen, was alle verwendeten
Event-Modelle unterstützen. Den kleinsten gemeinsamen Nenner sozusagen,
den man schnell mit C<Tk> identifizieren kann :)

Die API ist an die Event-API angelehnt, unterscheidet sich aber in einigen
Punkten. Die drei Standardbeispiele sehen bei C<AnyEvent> so aus:

   # Auf Daten warten:
   my $watcher = AnyEvent->io (fh => $fh, poll => 'r', cb => sub {
      # es kann nichtblockierend gelesen werden
   });
   # wird der watcher vergessen, wird er zerstört, deshalb muss man
   # ihn aufbewahren

   # _Ungefähr_ jede Stunde was tun:
   my $w;
   my $cb; $cb = sub {
      # tue was

      $w = AnyEvent->timer (after => 3600, cb => $cb);
   };
   $cb->();

   # Hauptschleife:
   AnyEvent->condvar->new->wait;

Statt eines Filedeskriptors oder Handles akzeptiert AnyEvent nur
letzteren (C<fh> statt C<fd>). Pollen kann man z.Zt. nur nach 'r'ead oder
'w'rite -Ereignissen, und Timer sind immer relativ zu "jetzt" und feuern
nur einmal.

Am fremdartigsten ist sicher das, was unter "Hauptschleife"
steht: AnyEvent zielt vor allem auf Modul-Autoren. Diese brauchen
manchmal eine Schnittstelle in die Hauptschleife, ohne sie direkt
aufzurufen. C<condvar>s (Condition Variables, Bedingungsvariablen) kann
man sich am ehesten als "Fertig-Indikator" vorstellen. Jede C<condvar>
hat zwei Methoden: C<wait>, mit dem auf das Erreichen der Bedingung
gewartet werden kann, und C<broadcast>, mit der an alle Interessenten ein
"Bedingung erfüllt"-Signal gesendet werden kann.

Beispielsweise implementiert das folgende Fragment eine Art interaktive
Shell, deren "quit"-Befehl das Programm beenden soll:

   use AnyEvent;

   my $want_to_quit = AnyEvent->condvar;

   my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
      my $command = <STDIN>;

      $command eq "quit"
         and $want_to_quit->broadcast
   });

   $want_to_quit->wait;

Dieses Beispiel benutzt eine Condition-Variable namens C<$want_to_quit>
("Beenden erwünscht"), die die Bedingung (wer hätte es gedacht) "Benutzer
wünscht das Beenden des Programms" ausdrückt.

C<< $want_to_quit->wait >> wartet daher, bis diese Bedingung
eintritt. Nebenher läuft aber die Ereignisverarbeitung weiter, bis
der Event-Callback das Kommando "quit" einliest und das Eintreten der
Bedingung C<broadcast>et.

In Modulen benutzt man C<condvars> am besten pro "Request", um das
Eintreten bestimmer Zustände (meistens "fertig") zu repräsentieren.

Wie man das macht und wozu das dient beschreibt der nächste Abschnitt.


=head1 Fallbeispiel Modul-API: IO::AIO und Coro::AIO

Das C<IO::AIO>-Modul bietet eine Schnittstelle für asynchrones I/O
an. D.h. man kann damit Dateien lesen, schreiben, löschen und vieles
mehr, ohne daß man auf das Ergebnis warten müsste. Keine Frage, es ist
ereignisgesteuert, oder besser gesagt, es wandelt I/O-Anfragen in einen
Strom von Ergebnisereignissen um.

Es stammt aus der Zeit vor AnyEvent und sollte deshalb völlig
unabhängig vom verwendeten Event-Modell benutzt werden können. Dies
wird erreicht, indem es einen Dateideskriptor zur Verfügung
stellt, der lesbar wird, sobald Ergebnisse vorliegen. Diesen
Dateideskriptor (C<IO::AIO::poll_fileno>) übergibt man einfach seinem
bevorzugten Event-Modell und sorgt dafür, daß bei Lesbarkeit die
C<IO::AIO::poll_cb>-Funktion aufgerufen wird.

C<IO::AIO> gibt in der Dokumentation Beispiele für die Integration in
eine Menge Event-Modelle an:

   # AnyEvent
   open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
   my $w = AnyEvent->io (fh => $fh, poll => 'r',
                         cb => sub { IO::AIO::poll_cb });

   # Event
   Event->io (fd => IO::AIO::poll_fileno,
              poll => 'r',
              cb => \&IO::AIO::poll_cb);

   # Glib/Gtk2
   add_watch Glib::IO IO::AIO::poll_fileno,
            in => sub { IO::AIO::poll_cb; 1 };

   # Tk
   Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
                             readable => \&IO::AIO::poll_cb);

   # Danga::Socket
   Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
                               \&IO::AIO::poll_cb);

Das Prinzip ist wirklich immer das gleiche.

Man kann IO::AIO auch ohne ein Event-Modell benutzen:

   # jede Menge Anfragen
   aio_xxx ... for 1..100000000;

   # warte bis es keine ausstehenden Requests mehr gibt:
   IO::AIO::poll_wait, IO::AIO::poll_cb
      while IO::AIO::nreqs;

   # naja, in neueren Versionen geht es auch so:
   IO::AIO::flush;

Das Modul C<Coro::AIO> bildet die C<IO::AIO>-API auf eine blockierende
aber Coroutinen-kompatible API ab. Dies geschieht programmatisch (es wurde
also nicht für jede IO::AIO::aio_*-Funktion eine Coro::AIO::aio_*-Funktion
implementiert).

Um dem Benutzer die Qual der Wahl eines Event-Modells zu ersparen, erzeugt
C<Coro::AIO> gleich einen AnyEvent-Watcher:

   our $FH; open $FH, "<&=" . IO::AIO::poll_fileno;
   our $WATCHER = AnyEvent->io (fh => $FH, poll => 'r'
                                cb => sub { IO::AIO::poll_cb });

Es ist nicht tragisch, wenn der mal nicht aufgerufen wird, weil der
Benutzer von C<Coro::AIO> andere Vorstellungen hat, solange nur
irgendjemand C<IO::AIO::poll_cb> aufruft.


=head1 Fallbeispiel Modul-API: Net-FCP und AnyEvent

C<Net::FCP> ist für das Freenet in etwa das, was LWP fürs Web ist. Meiner
Meinung nach ist die API von C<Net::FCP> geradezu ideal, da sie eine
sehr einfache Benutzung erlaubt (ähnlich LWP und LWP::Simple), und
trotzdem kompliziertere Anwendungen ermöglicht.

Freenet ist ein typisches Anfrage-Antwort-Protokoll, genau wie
HTTP. Die wichtigste Methode ist die C<client_get>-Methode, mit der man
Freenet-Objekte herunterladen kann:

   my $fcp = new Net::FCP;

   my $data = $fcp->client_get (
         "freenet:SSK@xK6UnCmOBL1bMf-VZBDTQfvYTFwPAgM/LiberalDecalogue//"
      );

Die Methode verhält sich (fast) wie C<LWP::Simple::get>: sie wartet so
lange, bis das Ergebnis angekommen ist oder ein Fehler aufgetreten ist
(letztere werden durch Exceptions weitergegeben).

=head3 Blockierende API

Alle Anfragen des Freenet-Protokolls (neben client_get gibt es noch viele
weitere) besitzen eine gleichnamige Methode, die eine Verbindung aufbaut,
die Anfrage losschickt und auf Antwort wartet:

   my $data = $fcp->client_get ($uri);
   $fcp->client_put ($uri, $metadata, $data, $htl);
   $fcp->generate_chk ($metadata, $data);
   ...

Für einfache Anwendungen reicht diese Schnittstelle völlig aus. Da Net::FCP
intern ereignisgesteuert ist, laufen solche Anfragen aber auch problemlos
in einer eigenen Coroutine, parallel zu anderen Anfragen, ohne daß der
aufrufende Code (oder Net::FCP) irgendetwas Spezielles machen müsste.

=head3 Nichtblockierende API

Tatsächlich sind alle Methoden autogeneriert (wie, wird noch beschrieben),
die Freenet-Abfragen durchführen, d.h. sie mussten nicht mal geschrieben
werden. Tatsächlich müssen "nur" Methoden geschrieben werden, die eine
Transaktion starten:

   my $transaction = $fcp->txn_client_get ($uri);

Diese Methoden erzeugen lediglich ein neues Objekt (eine Transaktion), das
den Zustand der gesamten Protokollabfrage darstellt und kehren I<sofort>
zum Aufrufer zurück. Man kann der Transaktion einen Callback übergeben,
der aufgerufen wird, sobald ein Ergebnis vorliegt:

   $transaction->cb (sub {
      # Juchhee, wir haben die Daten! Oder einen Fehler...
   });

Und natürlich kann man das Ergebnis auch abfragen:

   my $data = $transaction->result;
   # Entweder werden hier die Daten zurückgegeben,
   # oder es wird eine Exception ausgelöst.

Wenn die Ergebnisse schon vorliegen, blockiert C<result> nicht, ansonsten
wartete es, bis dies der Fall ist.

Das allgemeine Prinzip ist, jede Anfrage in zwei Teile aufzuteilen: Start
der Transaktion und Ankunft der Ergebnisse.

=head2 Benutzung

Diese beiden APIs erlauben eine erstaunliche Vielfalt an Nutzungsstilen:

=head3 Blockierend

Ganz einfach blockierend. Hier wäre z.B. eine einfache, wget-artige
Applikation, die eine Freenet-URL herunterlädt und die Daten ausgibt:

   # client_get liefetr eine Arrayref mit Metadaten und Daten.
   print Net::FCP->new->client_get (shift)->[1];

=head3 Blockierend, mit Coroutinen

Das hypothetische Modul C<Net::Supergeil> benutzt das Net::FCP-Modul zum
Herunterladen von Videos. Leider ist es selbst nicht ereignisgesteuert und
blockiert den Aufrufer ein paar Tage.

Kein Problem, wir stecken den Aufruf in eine Coroutine:

   use Coro;
   # Lade/wähle das Event-Modell:
   use Coro::Event;

   async {
      Net::Supergeil::lad_es_runter $uri, $file;
      print "Daten sind in $file\n";
   };

   # tue etwas anderes...
   ...
   Coro::Event::loop;

Das funktioniert deshalb, weil Net::FCP ereignisgesteuert arbeitet
und Coro::Event, sofern keine Ereignisse vorliegen, einfach andere
Coroutinen ausführt. Obwohl Net::Supergeil keine sehr hilfreiche API zur
Verfügung stellt, kann man es trotzdem Ereignisgesteuert einsetzen, weil
alle blockierenden Routinen, die es auf ruft, intern Ereignisgesteuert
arbeiten.

=head3 Nichtblockierend, Parallel

Durch die Aufteilung in Start- und Ergebnisteile kann man die Anfragen
einfach parallelisieren (was bei Freenet extrem wichtig ist):

   my @results = map $_->result,
                    map $fcp->txn_client_get ($_),
                       @uris;

Da mir gesagt wurde, C<map> sei sowas wie Magie, hier das ganze in
Javaspeak:

   my @txns;
   for my $url (@urls) {
      push @txns, $fcp->txn_client_get ($url);
   }
   my @results;
   for my $txn (@txns) {
      push @results, $txn->result;
   }

(Es gibt Leute, die behaupten, das wäre klarer und einfacher zu
maintainen).

Zuerst wird jede URL in eine Transaktion umgewandelt. Bis auf Erzeugen
einer Datenstruktur und einer Socket passiert dabei nicht viel, das ganze
geht also schnell.

Dann wird die C<result>-Methode jeder Transaktion bemüht. Da zu diesem
Zeitpunkt mit Sicherheit noch keine Ergebnisse vorliegen (schlicht
deshalb, weil nicht einmal der Verbindungsaufbau abgeschlossen ist),
blockiert C<result>.

Dies führt indirekt zu einem Sprung in die Hauptschleife des verwendeten
Event-Modells, wodurch alle Anfragen ins Rollen kommen und parallel
(genauer: zeitlich eng verzahnt) durchgeführt werden. Sind die Ergebnisse
einer Transaktion angekommen (manche dauern länger, manche sind schnell),
so wird die C<result>-Methode der nächsten Transaktion aufgerufen. Dann
gibt es wieder zwei Möglichkeiten: entweder es gibt schon Ergebnisse, dann
geht's sofort weiter, oder eben nicht, dann wird wieder blockiert und ein
bisschen weiter gearbeitet.

Das Schöne an dieser Art der Nutzung ist, daß überhaupt keine Aufrufe
irgendwelcher Event-Module auftauchen, und man sich auch nicht darum
kümmern braucht, welches Event-Modell benutzt wird.

=head3 Nichtblockierend, Continuation Passing

Das folgende Fragment lädt ein Freenet-Paket herunter. Ist es eine
Redirection, so lädt es die Seite herunter, auf die es zeigt:

   $fcp->txn_client_get ($uri)->cb ({
      my $data = $_[0]->result;
      if (ist ein redirect) {
         $fcp->txn_client_get ($redirect_uri)->cb ({
            my $data = $_[0]->result;
            # fertig
         });
      } else {
         # fertig
      }
   });

Für die ausgelassenen Teile ("fertig") bietet sich eine
C<< AnyEvent->condvar >> an:

   my $got_it = AnyEvent->condvar;

   # und statt "fertig":
   $got_it->broadcast;

=head3 Andere...

Prinzipiell läßt sich C<Net::FCP> auch in State-Maschinen
u.ä. einbauen: Net::FCP verhält sich wie ein Event-Modell für
Freenet-Ereignisse.

=head2 Implementation

Die Implementation ist vergleichsweise einfach und geradlinig. Ein gewisser
Grundaufwand ist nicht zu vermeiden, aber man erreicht mit wenig Aufwand
vergleichsweise viel.

Damit man wenig Aufwand treiben muss, gibt es eine Hilfsfunktion, die
sowohl die Methode mit C<txn_>-Präfix generiert als auch die ohne:

   my $txn = sub {
      my ($name, $sub) = @_;
      *{"txn_$name"} = $sub;
      *{$name} = sub { $sub->(@_)->result };
   };

Der Aufruf ist ganz einfach:

   $txn->(client_hello => sub {
      my ($self) = @_;
      $self->txn ("client_hello");
   });

Das erzeugt sowohl die C<client_hello>- als auch die
C<txn_client_hello>-Methode. Die Methode ohne C<txn_> ist immer nach
demselben Muster aufgebaut:

   txn_xxx(@_)->result

d.h. die Transaktion wird erzeugt und dann wird sofort C<< ->result >>
darauf aufgerufen. Das erzeugt dann die einfache blockierende API.

Für C<client_get> sieht es etwas komplizierter - aber im Prinzip genauso - aus:

   $txn->(client_get => sub {
      my ($self, $uri, $htl, $removelocal) = @_;
      
      $uri =~ s/^freenet://; $uri = "freenet:$uri";
      
      $self->txn (client_get => URI => $uri
                  hops_to_live => xeh (defined $htl ? $htl : 15),
                  remove_local_key => $removelocal ? "true" : "false");
   });

Da alle Anfragen/Transaktionen ähnlich ablaufen (Verbindungsaufbau,
Anfrage hin, Antwort her, Ende), definiert Net::FCP die C<txn>-Hilfsmethode, die
eine Transaktion erzeugt:

   sub txn {
      my ($self, $type, %attr) = @_;

      $type = touc $type;
       "Net::FCP::Txn::$type"->new (fcp => $self, type => tolc $type, attr => \%attr);
   }

Jeder Anfragetyp besitzt seine eigene Klasse,
z.B. C<Net::FCP::Txn::client_get>, die jeweils von C<Net::FCP::Txn>
abgeleitet ist.

Die C<new>-Methode erzeugt das Transaktionsobjekt und initiiert diese (ich
gebe nur die relevanten Zeilen an):

   sub new {
      my $class = shift;
      my $self = bless { @_ }, $class;

      $self->{signal} = AnyEvent->condvar;

C<< $self->{signal} >> ist das "Ergebnis vorhanden"-Signal, eine
C<condvar>. Dann wird eine Socket erzeugt und die Verbindung initiiert:

      socket my $fh, PF_INET, SOCK_STREAM, 0
         or Carp::croak "unable to create new tcp socket: $!";
      binmode $fh, ":raw";
      fcntl $fh, F_SETFL, O_NONBLOCK;
      connect $fh, (sockaddr_in $self->{fcp}{port}, inet_aton $self->{fcp}{host})
         and !$!{EWOULDBLOCK}
         and !$!{EINPROGRESS}
         and Carp::croak "FCP::txn: unable to connect to $self->{fcp}{host}:$self->{fcp}{port}: $!\n";

Nun wird der zu sendende Header in C<< $self->{sbuf} >> verstaut

      $self->{sbuf} =
         "\x00\x00\x00\x02"
         . (Net::FCP::touc $self->{type})
         . "\012$attr$data";

und ein Event-Watcher erzeugt. Wenn die Verbindung zustande kommt (oder
ein Fehler auftritt), wird die Socket schreibbar (genaugenommen blockiert
der Prozess nicht sofort, wenn man dann schreibt):

      $self->{w} = AnyEvent->io (fh => $fh, poll => 'w', cb => sub { $self->fh_ready_w });

Und fertig:

      $self
   }

Bis auf C<inet_aton> blockiert keiner der benutzten Aufrufe, und da die
normale Adresse des Freenet-Hosts C<127.0.0.1> ist, wird C<inet_aton>
eher selten blockieren. Das Erzeugen der Transaktion geschieht also "so
schnell wie es die CPU erlaubt".

=head3 Senden

Sobald die Socket "schreibbar" wird, wird die C<fh_ready_w>-Methode (in
etwa: Filehandle bereit zum Schreiben) aufgerufen. Diese versucht, so viel
der Anfrage ($self->{sbuf}) zu schreiben, wie die Socket annimmt:

   sub fh_ready_w {
      my ($self) = @_;

      my $len = syswrite $self->{fh}, $self->{sbuf};

Konnte etwas geschrieben werden, wird $self->{sbuf} entsprechend
gekürzt. Ist es danach leer, ist die gesamte Anfrage geschrieben worden,
und es wird in die Empfangsphase gegangen, indem der alte AnyEvent-Watcher
überschrieben (und damit gelöscht wird) und ein neuer Watcher erzeugt
wird, der auf "Daten lesbar" reagiert:

      if ($len > 0) {
         substr $self->{sbuf}, 0, $len, "";
         unless (length $self->{sbuf}) {
            $self->{w} = AnyEvent->io (fh => $self->{fh}, poll => 'r', cb => sub { $self->fh_ready_r });
         }

Der Rest der Methode kümmert sich um die Fehlerbehandlung:

      } elsif (defined $len) {
         $self->throw (Net::FCP::Exception->new (network_error => { reason => "unexpected end of file while writing" }));
      } else {
         $self->throw (Net::FCP::Exception->new (network_error => { reason => "$!" }));
      }
   }

Die Fehlerbehandlung ist übrigens nicht einfach ein Aufruf von C<die>. Die
Idee ist, daß es nicht allzu hilfreich ist, wenn irgendwo tief in
C<Net:FCP> ein Fehler auftritt, da nicht klar ist, wer für die Anfrage
verantwortlich ist. (Vielleicht werden mehrere Server gleichzeitig befragt,
aber einer wurde falsch angegeben. Ein Hinweis, welches Codefragment die
Anfrage in Auftrag gegeben hat, wäre in diesem Fall hilfreich.)

C<Net::FCP> merkt sich daher jeden aufgetretenen Fehler und bricht die
Transaktion ab:

   sub throw {
      my ($self, $exc) = @_;

      $self->{exception} = $exc;
      $self->set_result;
      $self->eof; # must be last to avoid loops
   }

Die Methode C<eof> schließt einfach die Socket und gibt eventuell andere
Ressourcen frei.  Die C<set_result>-Methode wird immer aufgerufen, wenn die
Transaktion ein Resultat hat (Daten, oder einen Fehler):

   sub set_result {
      my ($self, $result) = @_;

      $self->{result} = $result;
      $self->{cb}->($self) if exists $self->{cb};
      $self->{signal}->broadcast;
   }

Sie sorgt dafür, das ein eventuell gesetzter Callback sofort ausgeführt
wird und broadcastet das anfänglich erzeugte "fertig"-Signal.

=head3 Empfangen

Der Normalfall sollte aber das Erreichen der Empfangsphase sein. Sobald
Daten vorliegen, wird C<fh_read_r> aufgerufen. Prinzipiell genauso
aufgebaut wie C<fh_ready_w>, jedoch komplizierter, weil wir die Daten
gleich beim Empfang parsen:

   sub fh_ready_r {
      my ($self) = @_;
      
      if (sysread $self->{fh}, $self->{buf}, 65536, length $self->{buf}) {
         for (;;) {
            if ($self->{datalen}) {
               if (length $self->{buf} >= $self->{datalen}) {
                  $self->rcv_data (substr $self->{buf}, 0, delete $self->{datalen}, "");
               } else {
                  last;
               }
            } elsif ($self->{buf} =~ s/^DataChunk\015?\012Length=([0-9a-fA-F]+)\015?\012Data\015?\012//) {
               $self->{datalen} = hex $1;
            } elsif ($self->{buf} =~ s/^([a-zA-Z]+)\015?\012(?:(.+?)\015?\012)?EndMessage\015?\012//s) {
               $self->rcv ($1, {
                     map { my ($a, $b) = split /=/, $_, 2; ((Net::FCP::tolc $a), $b) }
                         split /\015?\012/, $2
               });
            } else {
               last;
            }
         }
      } else {
         $self->eof;
      }
   }

Das muss man jetzt nicht im Detail nachvollziehen, wichtig ist der Aufruf
von C<sysread>, der Daten an den Skalar C<< $self->{buf} >> I<anhängt>.
Sollten wieder Erwarten mal mehr als 64k Daten vorhanden sein, ist das
übrigens nicht schlimm, da die Methode dann fast sofort wieder aufgerufen
wird, solange, bis keine Daten mehr vorrätig sind.

Ist nach Meinung der Methode alles angekommen, was ankommen sollte,
wird die C<rcv>-Methode aufgerufen. Die macht noch ein bisschen was
Spezifisches, je nach Anfragetyp, und ruft ihrerseits wieder C<set_result>
auf.

Bei Dateiende wird C<eof> aufgerufen, was übrigens nicht I<nur> Ressourcen
freigibt, sondern auch einen Fehler auslöst, falls kein Resultat gesetzt
wurde, was z.B. beim Verbindungsabbruch mitten in der Empfangsphase
passiert.

=head3 Ergebnis

Ruft nun entweder der Callback oder jemand anders später die
C<result>-Methode auf, so prüft diese zuerst, ob ein Resultat vorliegt,
und wartet gegebenenfalls so lange, bis eines vorliegt:

   sub result {
      my ($self) = @_;

      $self->{signal}->wait unless exists $self->{result};

C<condvars> fügen sich sehr natürlich in derlei Programme ein, da sie
es ermöglichen, sowohl nichtblockierend als auch blockierend bestimmte
Ereignisse anzuzeigen.

Sollte ein Fehler aufgetreten sein, so wird die Exception sofort geworfen:

      die $self->{exception} if $self->{exception};

Ein Backtrace ist dann viel aussagekräftiger, da das Programm dort
abstürzt, wo die Daten verarbeitet werden sollen, was meistens
Rückschlüsse auf die Art der Daten zuläßt :)

Ansonsten bleibt nur, das Ergebnis zu liefern:

      $self->{result}
   }

Fertig!


Revision:	1.11
Committed:	Fri Jan 27 16:05:31 2006 UTC (20 years, 8 months ago) by root
Branch:	MAIN
Changes since 1.10:	+28 -23 lines
Log Message:	* empty log message *