Skip to content
Browse files

documentation revisions for 0.1001

  • Loading branch information...
1 parent 305dade commit 8b57feddf1f6f4ff6656d891d24acbbd4452c42a @rcaputo committed Apr 18, 2000
Showing with 60 additions and 47 deletions.
  1. +7 −4 Changes
  2. +45 −37 lib/POE/Kernel.pm
  3. +8 −6 lib/POE/Preprocessor.pm
View
11 Changes
@@ -13,10 +13,11 @@ make dist on it! 0.0910 is ``v0_0910''! For example:
cvs tag -Rc v0_10 .
]
-*** To Do:
-*** Overhaul Kernel and Session manpages' DESCRIPTIONs.
-*** Redocument the debugging constants (part of desc. overhaul).
-*** Verify POE::Preprocessor documentation.
+
+To Do
+-----
+
+Overhaul Kernel and Session manpages' DESCRIPTIONs.
0.1001 2000.??.?? (!!!)
@@ -51,6 +52,8 @@ or two statements.
Set ASSERT_DEFAULT to true in t/*.t so the tests are more thorough.
+Documented the ASSERT_* and TRACE_* constants.
+
Added t/03_aliases.t to test session aliases.
Added t/04_selects.t to test filehandle watchers.
View
82 lib/POE/Kernel.pm
@@ -89,6 +89,9 @@ macro remove_extra_reference (<session>,<tag>) {
{% ses_refcount_dec <session> %}
}
+# There is an string equality test in alias_resolve that should not be
+# made into a numeric equality test. <name> is often a string.
+
macro alias_resolve (<name>) {
# Resolve against sessions.
( (exists $self->[KR_SESSIONS]->{<name>})
@@ -100,7 +103,7 @@ macro alias_resolve (<name>) {
: ( (exists $self->[KR_ALIASES]->{<name>})
? $self->[KR_ALIASES]->{<name>}
# Resolve against self.
- : ( (<name> == $self)
+ : ( (<name> eq $self)
? $self
# Game over!
: undef
@@ -2802,86 +2805,91 @@ Sample usage:
# Display information about garbage collection, and display some
# profiling information at the end.
- sub POE::Kernel::DEB_GC () { 1 }
- sub POE::Kernel::DEB_PROFILE () { 1 }
+ sub POE::Kernel::TRACE_GARBAGE () { 1 }
+ sub POE::Kernel::ASSERT_REFCOUNT () { 1 }
use POE;
...
=over 4
=item *
-DEB_EVENTS
+TRACE_DEFAULT
+
+The value of TRACE_DEFAULT, which itself defaults to 0, is used as the
+default value for all the other TRACE_* constants.
+
+=item *
+
+TRACE_QUEUE
+
+Enables a runtime trace of POE's main event loop.
+
+=item *
+
+TRACE_PROFILE
-Enables a trace of events as they are enqueued and dispatched (or
-discarded). Also shows states' return values.
+Enables a runtime count of the events that have been dispatched and an
+end-run report of the collected statistics.
=item *
-DEB_GC
+TRACE_SELECT
-Enables sanity checks in POE's internal structure cleanup, after each
-Session is stopped, and again at the end of the program's run.
-Displays the results of sessions' garbage-collection checks, perhaps
-showing why a session isn't stopping when it ought to.
+Displays a runtime trace of select's arguments and return values.
=item *
-DEB_INSERT
+TRACE_EVENTS
-Trace the steps POE::Kernel->_enqueue_state() takes to find the
-locations of new events in its queue.
+Displays a runtime trace of events as they're enqueued and dispatched.
=item *
-DEB_MAIN
+TRACE_GARBAGE
-The first debugging constant. Prints "POE stopped." when
-POE::Kernel->run() stops.
+Displays a runtime trace of garbage checking and collecting.
=item *
-DEB_PROFILE
+ASSERT_DEFAULT
-When enabled, POE::Kernel collects a histogram of state names that
-were dispatched, and displays a report of them when POE::Kernel->run()
-stops.
+The value of ASSERT_DEFAULT, which itself defaults to 0, is used as
+the default value for all the other ASSERT_* constants. POE's t/*.t
+tests enable ASSERT_DEFAULT to turn on maximum error checking.
=item *
-DEB_QUEUE
+ASSERT_SELECT
-When enabled, POE::Kernel displays information about events in the
-queue.
+Causes POE to check for and die on fatal select() errors.
=item *
-DEB_REFCOUNT
+ASSERT_GARBAGE
-Enabling enables sanity checks and status displays on the number of
-references POE::Kernel holds on resources. These references are used
-to determine when things like filehandles are no longer being used.
+Enables a bunch of reference count checking during garbage collection.
+This verifies the state of POE's internal data structures.
=item *
-DEB_RELATION
+ASSERT_RELATIONS
-Enabling this causes POE::Kernel to examine parent/child relationships
-for problems.
+Ensures that sessions' parent/child relationships are consistent.
=item *
-DEB_SELECT
+ASSERT_SESSIONS
-When enabled, DEB_SELECT causes POE::Kernel to display running
-statistics about its select vectors and time-out status.
+Makes bad session references fatal. This can be helpful in situations
+where sessions aren't running as expected.
=item *
-DEB_STRICT
+ASSERT_REFCOUNT
-When enabled, POE::Kernel->post() and POE::Kernel->call() must be able
-to resolve an event's destination at post time.
+Dies if reference counts go negative. This is another internal
+consistency check on POE's data structures.
=back
View
14 lib/POE/Preprocessor.pm
@@ -352,10 +352,10 @@ POE::Preprocessor - A Macro Preprocessor
POE::Preprocessor is a Perl source filter that implements a simple
macro substitution language.
-The preprocessor defines a "macro" command:
+The preprocessor defines a "macro" compile-time directive:
- macro macro_name (parameter list) {
- macro code
+ macro macro_name (parameter_0, parameter_1) {
+ macro code ... parameter_0 ... parameter_1 ...
}
The parameter list is optional for macros that don't accept
@@ -364,7 +364,7 @@ parameters.
Macros are substituted into a program with a syntax borrowed from
Iaijutsu and altered slightly to jive with Perl's native syntax.
- {% macro_name parameter,list %}
+ {% macro_name parameter_0, parameter_1 %}
Constants are defined this way:
@@ -381,15 +381,17 @@ Or some other number:
Or continue where the previous one left off, which is necessary
because an enumeration can't span lines:
- enum + THIRTEENTH FOURTEENTH FIFTEENTH ...
+ enum + THIRTEENTH FOURTEENTH FIFTEENTH ...
=head1 BUGS
=over 2
=item *
-Macro invocations may not span lines, but macro definitions may.
+Source filters are line-based, and so is the macro language. The only
+constructs that may span lines are the brace-delimited macro
+definitions. And those *must* span lines.
=item *

0 comments on commit 8b57fed

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