home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / Resource.pm < prev    next >
Encoding:
Perl POD Document  |  2003-11-21  |  2.9 KB  |  96 lines
  1. # $Id: Resource.pm,v 1.3 2003/11/21 05:08:25 rcaputo Exp $
  2.  
  3. package POE::Resource;
  4.  
  5. use vars qw($VERSION);
  6. $VERSION = do {my@r=(q$Revision: 1.3 $=~/\d+/g);sprintf"%d."."%04d"x$#r,@r};
  7.  
  8. use Carp qw(croak);
  9.  
  10. sub new {
  11.   my $type = shift;
  12.   croak "$type is a virtual base class and not meant to be used directly";
  13. }
  14.  
  15. 1;
  16.  
  17. __END__
  18.  
  19. =head1 NAME
  20.  
  21. POE::Resource - documentation for POE's internal event watchers/generators
  22.  
  23. =head1 SYNOPSIS
  24.  
  25.   Varies.
  26.  
  27. =head1 DESCRIPTION
  28.  
  29. POE manages several types of information internally.  Its Resource
  30. classes are designed to manage those types of information behind tidy,
  31. encapsulated interfaces.  This allows us to test them individually, as
  32. well as re-implement them in C without porting POE::Kernel all at
  33. once.
  34.  
  35. Currently every POE::Resource class is sufficiently different from the
  36. rest that there isn't much to document here.  There are however
  37. similarities between them that should be noted.
  38.  
  39. While it's not currently the case, every resource should have
  40. initializer and finalizer functions.
  41.  
  42. Initializers act to link resources to POE::Kernel, usually by swapping
  43. lexically scoped variable references between Kernel.pm and each
  44. resource's source scopes.
  45.  
  46. Finalizers clean up any remaining data and also verify that each
  47. resource's subsystem was left in a consistent state.
  48.  
  49. At some future time, resources will be loaded dynamically and will
  50. need to register their initializers and finalizers with POE::Kernel.
  51. Otherwise POE::Kernel won't know which to call.
  52.  
  53. One common theme in resource implementations is that they don't need
  54. to perform much error checking, if any.  Resource methods are used
  55. internally by POE::Kernel and/or APIs (programmer interfaces), so it's
  56. up to them to ensure that they're used correctly.
  57.  
  58. Resource methods follow the naming convention _data_???_activity,
  59. where ??? is an abbreviation for the type of resource it belongs to:
  60.  
  61.   POE::Resource::Events      _data_ev_initialize
  62.   POE::Resource::FileHandles _data_handle_initialize
  63.   POE::Resource::Signals     _data_sig_initialize
  64.  
  65. Finalizer methods end in "_finalize".
  66.  
  67. Finalizers return true if a resource shut down cleanly, or false if
  68. there were inconsistencies or leaks during end-of-run checking.  The
  69. t/res/*.t tests rely on these return values.
  70.  
  71. We may be able to take advantage of this later by skimming
  72. POE::Kernel's namespace for initializers and finalizers automatically.
  73.  
  74. =head1 SEE ALSO
  75.  
  76. L<POE::Resource::Aliases>, 
  77. L<POE::Resource::Events>, 
  78. L<POE::Resource::Extrefs>, 
  79. L<POE::Resource::FileHandles>, 
  80. L<POE::Resource::SIDs>, 
  81. L<POE::Resource::Sessions>, 
  82. L<POE::Resource::Signals>
  83.  
  84. =head1 BUGS
  85.  
  86. This documentation, and resource specification, are incomplete.  We
  87. are developing it as a rationale after the fact for practices that
  88. have developed over several months.
  89.  
  90. =head1 AUTHORS & LICENSING
  91.  
  92. Please see L<POE> for more information about its authors,
  93. contributors, and POE's licensing.
  94.  
  95. =cut
  96.