Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

documentation revisions for 0.1001

  • Loading branch information...
commit 8b57feddf1f6f4ff6656d891d24acbbd4452c42a 1 parent 305dade
Rocco Caputo authored

Showing 3 changed files with 60 additions and 47 deletions. Show diff stats Hide diff stats

  1. +7 4 Changes
  2. +45 37 lib/POE/Kernel.pm
  3. +8 6 lib/POE/Preprocessor.pm
11 Changes
@@ -13,10 +13,11 @@ make dist on it! 0.0910 is ``v0_0910''! For example:
13 13 cvs tag -Rc v0_10 .
14 14 ]
15 15
16   -*** To Do:
17   -*** Overhaul Kernel and Session manpages' DESCRIPTIONs.
18   -*** Redocument the debugging constants (part of desc. overhaul).
19   -*** Verify POE::Preprocessor documentation.
  16 +
  17 +To Do
  18 +-----
  19 +
  20 +Overhaul Kernel and Session manpages' DESCRIPTIONs.
20 21
21 22
22 23 0.1001 2000.??.?? (!!!)
@@ -51,6 +52,8 @@ or two statements.
51 52
52 53 Set ASSERT_DEFAULT to true in t/*.t so the tests are more thorough.
53 54
  55 +Documented the ASSERT_* and TRACE_* constants.
  56 +
54 57 Added t/03_aliases.t to test session aliases.
55 58
56 59 Added t/04_selects.t to test filehandle watchers.
82 lib/POE/Kernel.pm
@@ -89,6 +89,9 @@ macro remove_extra_reference (<session>,<tag>) {
89 89 {% ses_refcount_dec <session> %}
90 90 }
91 91
  92 +# There is an string equality test in alias_resolve that should not be
  93 +# made into a numeric equality test. <name> is often a string.
  94 +
92 95 macro alias_resolve (<name>) {
93 96 # Resolve against sessions.
94 97 ( (exists $self->[KR_SESSIONS]->{<name>})
@@ -100,7 +103,7 @@ macro alias_resolve (<name>) {
100 103 : ( (exists $self->[KR_ALIASES]->{<name>})
101 104 ? $self->[KR_ALIASES]->{<name>}
102 105 # Resolve against self.
103   - : ( (<name> == $self)
  106 + : ( (<name> eq $self)
104 107 ? $self
105 108 # Game over!
106 109 : undef
@@ -2802,8 +2805,8 @@ Sample usage:
2802 2805
2803 2806 # Display information about garbage collection, and display some
2804 2807 # profiling information at the end.
2805   - sub POE::Kernel::DEB_GC () { 1 }
2806   - sub POE::Kernel::DEB_PROFILE () { 1 }
  2808 + sub POE::Kernel::TRACE_GARBAGE () { 1 }
  2809 + sub POE::Kernel::ASSERT_REFCOUNT () { 1 }
2807 2810 use POE;
2808 2811 ...
2809 2812
@@ -2811,77 +2814,82 @@ Sample usage:
2811 2814
2812 2815 =item *
2813 2816
2814   -DEB_EVENTS
  2817 +TRACE_DEFAULT
  2818 +
  2819 +The value of TRACE_DEFAULT, which itself defaults to 0, is used as the
  2820 +default value for all the other TRACE_* constants.
  2821 +
  2822 +=item *
  2823 +
  2824 +TRACE_QUEUE
  2825 +
  2826 +Enables a runtime trace of POE's main event loop.
  2827 +
  2828 +=item *
  2829 +
  2830 +TRACE_PROFILE
2815 2831
2816   -Enables a trace of events as they are enqueued and dispatched (or
2817   -discarded). Also shows states' return values.
  2832 +Enables a runtime count of the events that have been dispatched and an
  2833 +end-run report of the collected statistics.
2818 2834
2819 2835 =item *
2820 2836
2821   -DEB_GC
  2837 +TRACE_SELECT
2822 2838
2823   -Enables sanity checks in POE's internal structure cleanup, after each
2824   -Session is stopped, and again at the end of the program's run.
2825   -Displays the results of sessions' garbage-collection checks, perhaps
2826   -showing why a session isn't stopping when it ought to.
  2839 +Displays a runtime trace of select's arguments and return values.
2827 2840
2828 2841 =item *
2829 2842
2830   -DEB_INSERT
  2843 +TRACE_EVENTS
2831 2844
2832   -Trace the steps POE::Kernel->_enqueue_state() takes to find the
2833   -locations of new events in its queue.
  2845 +Displays a runtime trace of events as they're enqueued and dispatched.
2834 2846
2835 2847 =item *
2836 2848
2837   -DEB_MAIN
  2849 +TRACE_GARBAGE
2838 2850
2839   -The first debugging constant. Prints "POE stopped." when
2840   -POE::Kernel->run() stops.
  2851 +Displays a runtime trace of garbage checking and collecting.
2841 2852
2842 2853 =item *
2843 2854
2844   -DEB_PROFILE
  2855 +ASSERT_DEFAULT
2845 2856
2846   -When enabled, POE::Kernel collects a histogram of state names that
2847   -were dispatched, and displays a report of them when POE::Kernel->run()
2848   -stops.
  2857 +The value of ASSERT_DEFAULT, which itself defaults to 0, is used as
  2858 +the default value for all the other ASSERT_* constants. POE's t/*.t
  2859 +tests enable ASSERT_DEFAULT to turn on maximum error checking.
2849 2860
2850 2861 =item *
2851 2862
2852   -DEB_QUEUE
  2863 +ASSERT_SELECT
2853 2864
2854   -When enabled, POE::Kernel displays information about events in the
2855   -queue.
  2865 +Causes POE to check for and die on fatal select() errors.
2856 2866
2857 2867 =item *
2858 2868
2859   -DEB_REFCOUNT
  2869 +ASSERT_GARBAGE
2860 2870
2861   -Enabling enables sanity checks and status displays on the number of
2862   -references POE::Kernel holds on resources. These references are used
2863   -to determine when things like filehandles are no longer being used.
  2871 +Enables a bunch of reference count checking during garbage collection.
  2872 +This verifies the state of POE's internal data structures.
2864 2873
2865 2874 =item *
2866 2875
2867   -DEB_RELATION
  2876 +ASSERT_RELATIONS
2868 2877
2869   -Enabling this causes POE::Kernel to examine parent/child relationships
2870   -for problems.
  2878 +Ensures that sessions' parent/child relationships are consistent.
2871 2879
2872 2880 =item *
2873 2881
2874   -DEB_SELECT
  2882 +ASSERT_SESSIONS
2875 2883
2876   -When enabled, DEB_SELECT causes POE::Kernel to display running
2877   -statistics about its select vectors and time-out status.
  2884 +Makes bad session references fatal. This can be helpful in situations
  2885 +where sessions aren't running as expected.
2878 2886
2879 2887 =item *
2880 2888
2881   -DEB_STRICT
  2889 +ASSERT_REFCOUNT
2882 2890
2883   -When enabled, POE::Kernel->post() and POE::Kernel->call() must be able
2884   -to resolve an event's destination at post time.
  2891 +Dies if reference counts go negative. This is another internal
  2892 +consistency check on POE's data structures.
2885 2893
2886 2894 =back
2887 2895
14 lib/POE/Preprocessor.pm
@@ -352,10 +352,10 @@ POE::Preprocessor - A Macro Preprocessor
352 352 POE::Preprocessor is a Perl source filter that implements a simple
353 353 macro substitution language.
354 354
355   -The preprocessor defines a "macro" command:
  355 +The preprocessor defines a "macro" compile-time directive:
356 356
357   - macro macro_name (parameter list) {
358   - macro code
  357 + macro macro_name (parameter_0, parameter_1) {
  358 + macro code ... parameter_0 ... parameter_1 ...
359 359 }
360 360
361 361 The parameter list is optional for macros that don't accept
@@ -364,7 +364,7 @@ parameters.
364 364 Macros are substituted into a program with a syntax borrowed from
365 365 Iaijutsu and altered slightly to jive with Perl's native syntax.
366 366
367   - {% macro_name parameter,list %}
  367 + {% macro_name parameter_0, parameter_1 %}
368 368
369 369 Constants are defined this way:
370 370
@@ -381,7 +381,7 @@ Or some other number:
381 381 Or continue where the previous one left off, which is necessary
382 382 because an enumeration can't span lines:
383 383
384   - enum + THIRTEENTH FOURTEENTH FIFTEENTH ...
  384 + enum + THIRTEENTH FOURTEENTH FIFTEENTH ...
385 385
386 386 =head1 BUGS
387 387
@@ -389,7 +389,9 @@ because an enumeration can't span lines:
389 389
390 390 =item *
391 391
392   -Macro invocations may not span lines, but macro definitions may.
  392 +Source filters are line-based, and so is the macro language. The only
  393 +constructs that may span lines are the brace-delimited macro
  394 +definitions. And those *must* span lines.
393 395
394 396 =item *
395 397

0 comments on commit 8b57fed

Please sign in to comment.
Something went wrong with that request. Please try again.