From a502c723a67c300f435652f0756e0f85b44efd85 Mon Sep 17 00:00:00 2001 From: Ruslan Osmanov Date: Thu, 27 Dec 2012 10:09:23 +0000 Subject: [PATCH] Add: docs for evwatcher, evtimer Fix: missing evio, evstat method docs git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328905 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/ev/evio/createstopped.xml | 16 ++-- reference/ev/evstat/set.xml | 46 ++-------- reference/ev/evtimer.xml | 83 +++++++++++------ reference/ev/evtimer/again.xml | 52 +++++------ reference/ev/evtimer/construct.xml | 118 +++++++++++++++++++------ reference/ev/evtimer/createstopped.xml | 74 +++++++++------- reference/ev/evtimer/set.xml | 49 +++------- reference/ev/evwatcher/clear.xml | 51 +++-------- reference/ev/evwatcher/construct.xml | 42 --------- reference/ev/evwatcher/feed.xml | 43 ++------- reference/ev/evwatcher/getloop.xml | 41 ++------- reference/ev/evwatcher/invoke.xml | 43 ++------- reference/ev/evwatcher/keepalive.xml | 53 +++++------ reference/ev/evwatcher/setcallback.xml | 42 ++------- reference/ev/evwatcher/start.xml | 34 ++----- reference/ev/evwatcher/stop.xml | 33 ++----- 16 files changed, 312 insertions(+), 508 deletions(-) diff --git a/reference/ev/evio/createstopped.xml b/reference/ev/evio/createstopped.xml index dc0c5841f2..8a6cc2b410 100644 --- a/reference/ev/evio/createstopped.xml +++ b/reference/ev/evio/createstopped.xml @@ -4,19 +4,21 @@ EvIo::createStopped - The createStopped purpose + Create stopped EvIo watcher object &reftitle.description; final - public static voidEvIo::createStopped - stringfd - stringevents - stringcallback - stringdata - stringpriority + public static EvIoEvIo::createStopped + mixedfd + intevents + callablecallback + mixeddata&null; + intpriority0 The same as EvIo::__construct, but doesn't start diff --git a/reference/ev/evstat/set.xml b/reference/ev/evstat/set.xml index c81295f361..e235dd1147 100644 --- a/reference/ev/evstat/set.xml +++ b/reference/ev/evstat/set.xml @@ -4,7 +4,7 @@ EvStat::set - The set purpose + Configures the watcher @@ -12,14 +12,12 @@ public voidEvStat::set stringpath - stringinterval + doubleinterval - + Configures the watcher. - &warn.undocumented.func; - @@ -29,7 +27,7 @@ path - + The path to wait for status changes on. @@ -37,7 +35,9 @@ interval - + Hint on how quickly a change is expected to be detected and should + normally be specified as 0.0 to let + libev choose a suitable value. @@ -47,40 +47,10 @@ &reftitle.returnvalues; - + &return.void; - - &reftitle.examples; - - <function>EvStat::set</function> example - - -]]> - - &example.outputs.similar; - - - - - - - - - &reftitle.seealso; - - - - -
@@ -46,6 +75,8 @@ remaining + &InheritedProperties; + &Methods; @@ -63,47 +94,41 @@
&reftitle.properties; - - is_active - - - - - - data - - - - - - is_pending - - - - - - priority - - - - repeat - + + If repeat is 0.0, then it will automatically be stopped once the timeout + is reached. If it is positive, then the timer will automatically be + configured to trigger again every repeat seconds later, until stopped + manually. + remaining - + + Returns the remaining time until a timer fires. If the timer is active, + then this time is relative to the current event loop time, + otherwise it's the timeout value currently configured. + + + That is, after instanciating an EvTimer with an + after value of 5.0 and + repeat value of 7.0, + remaining returns 5.0. When the + timer is started and one second passes, remaining + will return 4.0. When the timer expires and is + restarted, it will return roughly 7.0(likely + slightly less as callback invocation takes some time too), and so on. +
- &reference.ev.entities.evtimer; diff --git a/reference/ev/evtimer/again.xml b/reference/ev/evtimer/again.xml index 64338e0288..3f9a0a25a9 100644 --- a/reference/ev/evtimer/again.xml +++ b/reference/ev/evtimer/again.xml @@ -4,7 +4,7 @@ EvTimer::again - The again purpose + Restarts the timer watcher @@ -14,10 +14,29 @@ - + This will act as if the timer timed out and restart it again if it is + repeating. The exact semantics are: - &warn.undocumented.func; + + + + if the timer is pending, its pending status is cleared. + + + + + if the timer is started but non-repeating, stop it (as if it timed out). + + + + + if the timer is repeating, either start it if necessary (with the + repeat value), or reset the running timer to the + repeat value. + + + @@ -29,37 +48,14 @@ &reftitle.returnvalues; - + &return.void; - - &reftitle.examples; - - <function>EvTimer::again</function> example - - -]]> - - &example.outputs.similar; - - - - - - - &reftitle.seealso; - + EvWatcher::stop diff --git a/reference/ev/evtimer/construct.xml b/reference/ev/evtimer/construct.xml index 5429fa21f4..c24dbff102 100644 --- a/reference/ev/evtimer/construct.xml +++ b/reference/ev/evtimer/construct.xml @@ -4,25 +4,25 @@ EvTimer::__construct - The __construct purpose + Constructs an EvTimer watcher object &reftitle.description; public EvTimer::__construct - stringafter - stringrepeat - stringcallback - stringdata - stringpriority + doubleafter + doublerepeat + callablecallback + mixeddata&null; + intpriority0 - + Constructs an EvTimer watcher object. - &warn.undocumented.func; - @@ -32,7 +32,7 @@ after - + Configures the timer to trigger after after seconds. @@ -40,7 +40,10 @@ repeat - + If repeat is 0.0, then it will automatically be stopped once the timeout + is reached. If it is positive, then the timer will automatically be + configured to trigger again every repeat seconds later, until stopped + manually. @@ -48,7 +51,7 @@ callback - + See Watcher callbacks. @@ -56,7 +59,7 @@ data - + Custom data associated with the watcher. @@ -64,7 +67,7 @@ priority - + Watcher priority @@ -74,37 +77,98 @@ &reftitle.returnvalues; - + Returns EvTimer object on success. &reftitle.examples; - - <function>EvTimer::__construct</function> example - + + Simple timers + stop(); + // Stop the watcher if further calls cause more than 10 iterations + Ev::iteration() >= 10 and $w->stop(); +}); + +// Create stopped timer. It will be inactive until we start it ourselves +$w_stopped = EvTimer::createStopped(10, 5, function($w) { + echo "Callback of a timer created as stopped\n"; + + // Stop the watcher after 2 iterations + Ev::iteration() >= 2 and $w->stop(); +}); + +// Loop until Ev::stop() is called or all of watchers stop +Ev::run(); + +// Start and look if it works +$w_stopped->start(); +echo "Run single iteration\n"; +Ev::run(Ev::RUN_ONCE); + +echo "Restart the second watcher and try to handle the same events, but don't block\n"; +$w2->again(); +Ev::run(Ev::RUN_NOWAIT); + +$w = new EvTimer(10, 0, function() {}); +echo "Running a blocking loop\n"; +Ev::run(); +echo "END\n"; ?> ]]> - - &example.outputs.similar; - + + &example.outputs.similar; + - - + + - &reftitle.seealso; - + EvTimer::createStopped + EvPeriodic + ev_timer - relative and optionally repeating timeouts + Be smart about timeouts diff --git a/reference/ev/evtimer/createstopped.xml b/reference/ev/evtimer/createstopped.xml index b78665c7d6..7affce2e28 100644 --- a/reference/ev/evtimer/createstopped.xml +++ b/reference/ev/evtimer/createstopped.xml @@ -4,26 +4,28 @@ EvTimer::createStopped - The createStopped purpose + Creates EvTimer stopped watcher object &reftitle.description; final - public static voidEvTimer::createStopped - stringafter - stringrepeat - stringcallback - stringdata - stringpriority + public static EvTimerEvTimer::createStopped + doubleafter + doublerepeat + callablecallback + mixeddata&null; + intpriority0 - + Creates EvTimer stopped watcher object. Unlike + EvTimer::__construct, this method doesn't start the + watcher automatically. - &warn.undocumented.func; - @@ -33,7 +35,7 @@ after - + Configures the timer to trigger after after seconds. @@ -41,7 +43,10 @@ repeat - + If repeat is 0.0, then it will automatically be stopped once the timeout + is reached. If it is positive, then the timer will automatically be + configured to trigger again every repeat seconds later, until stopped + manually. @@ -49,7 +54,7 @@ callback - + See Watcher callbacks. @@ -57,7 +62,7 @@ data - + Custom data associated with the watcher. @@ -65,47 +70,56 @@ priority - + Watcher priority + &reftitle.returnvalues; - + Returns EvTimer watcher object on success. &reftitle.examples; - - <function>EvTimer::createStopped</function> example - + + Monotor changes of /var/log/messages. Avoid missing updates by means of one second delay + stop(); -/* ... */ + $stat = $w->data; + // 1 second after the most recent change of the file + printf("Current size: %ld\n", $stat->attr()['size']); +}); + +$stat = new EvStat("/var/log/messages", 0., function () use ($timer) { + // Reset timer watcher + $timer->again(); +}); + +$timer->data = $stat; + +Ev::run(); ?> ]]> - - &example.outputs.similar; - - - - + + - &reftitle.seealso; - + EvTimer::__construct + EvPeriodic diff --git a/reference/ev/evtimer/set.xml b/reference/ev/evtimer/set.xml index dc1bc7f6e3..41c24911dd 100644 --- a/reference/ev/evtimer/set.xml +++ b/reference/ev/evtimer/set.xml @@ -4,22 +4,20 @@ EvTimer::set - The set purpose + Configures the watcher &reftitle.description; public voidEvTimer::set - stringafter - stringrepeat + doubleafter + doublerepeat - + Configures the watcher - &warn.undocumented.func; - @@ -29,7 +27,7 @@ after - + Configures the timer to trigger after after seconds. @@ -37,7 +35,10 @@ repeat - + If repeat is 0.0, then it will automatically be stopped once the timeout + is reached. If it is positive, then the timer will automatically be + configured to trigger again every repeat seconds later, until stopped + manually. @@ -47,40 +48,10 @@ &reftitle.returnvalues; - + &return.void; - - &reftitle.examples; - - <function>EvTimer::set</function> example - - -]]> - - &example.outputs.similar; - - - - - - - - - &reftitle.seealso; - - - - -