Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

485 lines (345 sloc) 17.1 kB
$Id$
Things to do to POE, many of which will break existing programs.
Please use POE's mailing list (see the main POE manpage) to comment on
proposed changes.
As with the CHANGES file, things which may break existing programs
will be marked with "(!!!)". Since these are long-term plans,
however, actual code breakage will not occur for at least a month
after release.
===================================
Depreciations & Changes In Progress
===================================
These changes have begun, or will shortly. Their remaining steps are
still open to discussion, but the changes will go through in one form
or another.
--------------------------
XyzState to XyzEvent (!!!)
--------------------------
In the wheels, rename XyzState to XyzEvent everywhere. Wheels don't
define states, they emit events. Callivg Wheels' parameters XyzState
has been inconsistent and confusing. It's bitten a lot of people.
Call them what they are instead.
To do:
* Release version 0.15, and announce the depreciation.
* Wait at least 28 days (until ????.??.??) before continuing this
change schedule. This gives people time to adapt their production
code to the new parameters before warnings start.
* Add depreciation warnings when XyzState is used. This will prompt
late developers to adapt their code.
* Release version ?.??, and announce the next phase of XyzState
depreciation.
* Wait at least 28 days (until ????.??.??) before continuing this
change schedule. This gives people time to adapt their production
code to avoid the depreciation warnings and subsequent breakage.
* Remove XyzState warnings and support altogether.
* Release version ?.??, and announce that the XyzState to XyzEvent
depreciation has been completed.
-----------------------
Improve Alarm Interface
-----------------------
This change adds new features without breaking the way old ones work.
To do:
* Release version 0.15, and announce the new interface.
* Optimize new functions. Currently there are chunks of common code
which have been copied, pasted, and altered for their new
environments. Some of this can be made into macros.
Notes:
+ alarm_set(), alarm_adjust(), and alarm_remove() are done
+ delay_set() is done
+ alarm_remove_all() is done
- decided against alarm_remove_by_event(); use alarm() instead
- decided against alarm_remove_by time(); it's not very useful
----------------------------------
Depreciate queue_peek_alarms (!!!)
----------------------------------
The new alarm functions let programs track their alarms by ID, so they
no longer need to peek into POE's alarm queue.
To do:
* Release version 0.15, and announce the depreciation.
* Wait at least 28 days (until ????.??.??) before continuing this
change schedule. This gives people time to adapt their production
code to the new parameters before warnings start.
* Add depreciation warnings to queue_peek_alarms(). This will prompt
late developers to adapt their code.
* Release ?.??, and announce the next phase of depreciation.
* Wait at least 28 days (until ????.??.??) before continuing this
change schedule. This gives people time to adapt their production
code to avoid the depreciation warnings and subsequent breakage.
* Remove queue_peek_alarms() altogether.
* Release version ?.??, and announce that the depreciation schedule is
complete.
========================================
Depreciations & Changes Being Considered
========================================
These changes are under consideration. They have not begun, and they
may not ever be made. These are proto-plans being considered and made
ready for deployment.
---------------------------------------
Give Exported Constants Some Prefix(es)
---------------------------------------
<Micksa> eep, poe uses yet another calling convention
<Micksa> like:
<Micksa> my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
<Fletch> that's the normal convention, it just doesn't hardcode what
order particular arguments will be passed
<Micksa> it's, like, the 4th way I've seen so far for passing named
parameters.
<Fletch> it's so that if calling order ever changes programs that use
the symbolic constants don't break
<Fletch> it's really no different than say
`my($kernel,$heap)=@_[0,3]', just that the 0 and 3 come from
constant subs rather than magic numbers
<Micksa> problem is, the symbolic constants are rather likely to
clash.
<Fletch> maybe there could be an option to prefix them, like
poe_KERNEL or P_KERNEL?
<Micksa> *shrug*
That sounds like a good idea.
-------------------------------------------
Change Internal Helpers To Static Functions
-------------------------------------------
Despite recent optimizations in perl 5, object methods are still a wee
bit slower than function calls. Furthermore, those changes aren't in
older versions of perl where POE still runs fine.
Because of Kernel restructuring in 0.05_02 (1999.01.12) prohibiting
multiple Kernel instances, we can finally make POE::Kernel's private
methods static functions.
What do we get? Better performance (by a factor of 3 or so) in older
versions of perl. Less argument passing internally (no $self; the
lexical $poe_kernel instead). Greater encapsulation, but who cares
about that?
This is a relatively easy change, and it would make a good starter
project for someone who wants to get familiar with Kernel.pm and
Kernel/*.pm.
------------------------------------------
Signal Handler Return Values Must Go (!!!)
------------------------------------------
Signal handlers' return values are significant, determining whether
the handler has handled a signal, which in turn determines whether the
session will survive a terminal signal dispatch. This is the only
time where a state/event handler's return value is significant within
POE itself, and it's incongruous with the rest of the library. It's
also really easy to accidentally handle (or not) a signal by mistake:
simply implicitly return some random value.
To do:
* Add a POE::Kernel method: handle_signal().
This will indicate that the currently dispatched signal has been
handled for the session. Should it also affect all sessions? For
example, if one session handles SIGINT, would they all remain alive?
* Change the documentation to list handle_signal() as the proper way
to handle terminal signals.
* Run a complete test/coverage suite to make sure the current signal
handling code is not broken in the process of adding the new code.
* Add new tests for handle_signal() to make sure it works, and run a
complete test/coverage suit to verify that.
* Port the samples to use handle_signal() instead of return values.
* Release version ?.??, and announce the depreciation.
* Wait at least 28 days (until ????.??.??) before continuing this
change schedule. This gives people time to adapt their production
code to the new signal handling method before the warnings start.
* Add depreciation warnings whenever a terminal signal is handled by
its return value instead of the new handle_signal() method.
* Release version ?.??, and announce the next phase of the signal
handler depreciation.
* Wait at least 28 days (until ????.??.??) before continuing this
change schedule. This gives people time to adapt their production
code to avoid the depreciation warnings and subsequent breakage.
* Remove the code to recognize implicit signal handling due to
handlers' return values, making the handle_signal() method the only
way to do this.
* Release version ?.??, and announce that signal handlers' return
values have been completely depreciated.
----------------------
Batch Remove Resources
----------------------
Peter J. Braam would like a way to flush all pending events for a
session. This would be FIFO events, since there would already be a
method for alarms.
Kirill would like a way to batch-remove all selects when it's time for
a session to shut down.
+ alarm_remove_all() is done
To do:
* Add select_remove_all()
* Add event_remove_all()
Notes:
Other resources which keep a session alive: extra reference counts,
and aliases. Should there be batch remove functions for these as
well?
I'm starting to worry about the side effects of stopping sessions
willy-nilly. Is there a good example of stopping a session while it's
busy processing events? "Good" means the session won't corrupt
anything by not handling whatever is in its queue.
What of everything_remove_all() ?
----------------------------------
SIGTSTP Does the Wrong Thing (???)
----------------------------------
Gordon Matzigkeit writes (16 Feb 2001):
| If you haven't already, would you please add TSTP as a signal that
| should not be messed with in POE::Kernel:
|
| if (POE_USES_EVENT) { # include
| # If Event is available, register a signal watcher with it.
| # Don't register a SIGKILL handler, though, because Event
| # doesn't like that.
| if ($signal ne 'KILL' and $signal ne 'STOP'
| and $signal ne 'TSTP' # <-- HERE
| ) {
| Event->signal( signal => $signal,
| cb => \&_event_signal_handler_generic
| );
| }
I responded:
| I think a more correct implementation might set up TSTP and CONT
| handlers like in _APUE_'s program 10.22. That way, POE can
| gracefully suspend and resume itself while also propagating TSTP and
| CONT signals to sessions so they too can perform pause/resume tasks.
The code hasn't been designed yet, but here's the code from program
10.22 so I don't have to keep looking in the book.
int main (void) {
int n;
char buf[BUFSIZE];
/* only catch SIGTSTP if we're running in a job-control shell */
if (signal(SIGTSTP, SIG_IGN) == SIG_DFL)
signal(SIGTSTP, sig_tstp);
/* ... code to do stuff ... */
exit(0);
}
static void sig_tstp(int signo) { /* signal handler for SIGTSTP */
sigset_t mask;
/* ... code to set up us the suspend ... */
/* unblock SIGTSTP, since it's blocked while we're handling it */
sigemptyset(&mask);
sigaddset(&mask, SIGTSTP);
sigprocmask(SIG_UNBLOCK, &mask, null);
signal(SIGTSTP, SIG_DFL); /* reset disposition to default */
kill(getpid(), SIGTSTP); /* and send the signal to ourself */
/* kill won't return until we receive SIGCONT or something */
signal(SIGTSTP, sig_tstp); /* reestablish signal handler */
/* ... code to set up us the resume ... */
return;
}
-----------------------
ARG0..ARG9 May Go (!!!)
-----------------------
HEAP, KERNEL, SESSION, and the other event handler parameter constants
were introduced to eliminate a dependence on their positions in @_.
However, the ARG0..ARG9 parameters aren't descriptive and still
contain position dependence. This robs event parameters of many of
the benefits of using symbolic constants in the first place.
This is the current plan to depreciate them:
* Introduce new constants for the different built-in events. Leave
ARG0..ARG9 for user parameters.
* Document the new constants instead of ARG0..ARG9.
* Document that parameters may move around in the future, so their
positions in ARG0..ARG9 will not be guaranteed.
* Release version ?.??.
* Wait at least 28 days (until ????.??.??) before continuing this
depreciation schedule, to give people time to react to the initial
round of changes.
* Generate warnings when ARG0..ARG9 are used for built-in events.
This will require some logic within those subs, removing their
constant nature and slowing things down in general.
* Release version ?.??, and announce that the ARG0..ARG9 built-in
parameter depreciation is proceding apace.
* Wait at least 29 days (until ????.??.??) before continuing this
depreciation schedule, to give people time to react to the warnings
and adapt their code to the new symbolic constants.
* Remove the warnings from ARG0..ARG9, making them constants again and
speeding things up once more.
* Release version ?.??, and announce that the ARG0..ARG9 built-in
parameter depreciation has completed.
----------------------------
Spin Off Useful Technologies
----------------------------
POE only really needs a few modules. The rest are options which may
not always be needed, or they're stand-alone modules that someone else
may find useful. For example, POE::Filter::*; POE::Preprocessor; and
POE::Pipe::* are useful by themselves. Wheels are pretty useful, but
they're not always necessary. It may be both useful and convenient to
split POE into smaller distributions and present one or more Bundles
to selectively load just the parts that are needed.
This is the current plan to spin off useful modules from POE:
* Develop a real plan for this. Most of this is tentative.
* Organize subsets of POE into useful bundles, and document them.
Make Bundle::POE the default.
* Split out wheels?
* Split out the Preprocessor? Should it remain a POE::* module?
* Split out filters? They're useful by themselves; should they remain
POE::* modules?
* The samples are huge and obscure. Split them into a separate
distribution which doesn't install itself.
* Most of the documentation is theory and usage, and it doesn't really
fit in manpages for modules themselves. Split it into separate POD
files, and maybe split them into Bundle::POE::Docs.
-----------------------------------------
Make Driver::SysRW the Default for Wheels
-----------------------------------------
This is a quick, inexpensive change. Driver::SysRW is the only driver
to be developed/used over the course of like three years. Make it a
default so people can stop typing it.
This should be an easy fix, but it involves tweaking several wheels.
It might be a nice introduction to wheels for someone who wants to
know more about them.
----------------------------------------
Make Filter::Line the Default for Wheels
----------------------------------------
This is an inexpensive change, but it has dubious value. Think about
it some more first.
This should be an easy fix, but it involves tweaking several wheels.
It might be a nice introduction to wheels for someone who wants to
know more about them.
----------------------------------------------------
Split Dual-Mode Functions into xyz_set and xyz_clear
----------------------------------------------------
This would make the functions' purposes more clear and eliminate some
branches that are currently tested all the time. The existing
dual-mode functions could remain as thunks for the single-purpose
ones.
The "June 2001" alarms functions already do this. What about
select_xyz and the others?
----------------------------------------------------------------
Evaluate Torvald Riegel's Throttled ReadWrite Wheel Design (???)
----------------------------------------------------------------
Torvald has patched POE::Wheel::ReadWrite to perform throttled reads,
but I'm not happy with the idea of ReadWrite holding buffered data.
To do:
* Distill Torvald's e-mail on the subject and include a summary here.
* Determine whether his changes are extensible or will force ReadWrite
development into a dead end.
------------------------------------------------------
Evaluate Torvald Riegel's Synchronous NFA Design (???)
------------------------------------------------------
Torvald wants POE::NFA to run entirely synchronously like a proper
nondeterministic finite state machine ought to. I'm against that
because I haven't seen a proper need for it and it puts what I see as
an artificial limit on the class.
To do:
* Distill Torvald's e-mail on the subject and include a summary here.
* Determine whether his design can be implemented in a way that
doesn't limit NFA to a strictly correct NFA design. Asynchronous
NFA events are useful and should also be supported.
------------------------------
Delay Garbage Collection (???)
------------------------------
POE's garbage collection can be slow. It would be very cool to
schedule this in the "dead" time between events. Especially in
instances where the next event is a timer and we have a few seconds of
nothing to do.
A lot of things rely on timely garbage collection, though. _parent
and _child events. Referential integrity. Things would be a mess
between _stop and the delayed garbage collection.
Delaying alarm GC might be doable. We can flag alarms as "dead" in
the ID->time hash and discard them as they come to the front of the
queue. In idle times when there are no FIFO events and the next alarm
is more than 1/10 second away, we can sweep the alarm queue and pull
out the dead ones.
It will take a fair amount of planning to pull this off correctly.
I'm just documenting it for now so I don't forget.
-----------------------------------
Clean up ASSERT_* and TRACE_* Flags
-----------------------------------
Especially ASSERT_USAGE, ASSERT_RETURNS and TRACE_RETURNS which are
getting silly. Make this stuff macros, at the very least.
===
EOT
===
Jump to Line
Something went wrong with that request. Please try again.