0.005 release
[poe-xs-queue-array.git] / Array.pm
1 package POE::XS::Queue::Array;
2 use strict;
3 use vars qw(@ISA $VERSION);
4 use POE::Queue;
5
6 BEGIN {
7   @ISA = qw(POE::Queue);
8   $VERSION = '0.005';
9   eval {
10     # try XSLoader first, DynaLoader has annoying baggage
11     require XSLoader;
12     XSLoader::load('POE::XS::Queue::Array' => $VERSION);
13     1;
14   } or do {
15     require DynaLoader;
16     push @ISA, 'DynaLoader';
17     bootstrap POE::XS::Queue::Array $VERSION;
18   }
19 }
20
21 # lifted from POE::Queue::Array
22 sub ITEM_PRIORITY () { 0 }
23 sub ITEM_ID       () { 1 }
24 sub ITEM_PAYLOAD  () { 2 }
25
26 sub import {
27   my $package = caller();
28   no strict 'refs';
29   *{ $package . '::ITEM_PRIORITY' } = \&ITEM_PRIORITY;
30   *{ $package . '::ITEM_ID'       } = \&ITEM_ID;
31   *{ $package . '::ITEM_PAYLOAD'  } = \&ITEM_PAYLOAD;
32 }
33
34 # everything else is XS
35 1;
36
37 __END__
38
39 =head1 NAME
40
41 POE::XS::Queue::Array - an XS implementation of POE::Queue::Array.
42
43 =head1 SYNOPSIS
44
45 See POE::Queue.
46
47 =head1 DESCRIPTION
48
49 This class is an implementation of the abstract POE::Queue interface.
50 It implements a priority queue using C, with an XS interface supplied.
51
52 The current implementation could use some optimization, especially for
53 large queues.
54
55 Please see the POE::Queue documentation, which explains this one's
56 functions, features, and behavior.
57
58 The following extra methods are added beyond POE::Queue::Array:
59
60 =over
61
62 =item dump
63
64 Dumps the internal structure of the queue to stderr.
65
66 =item verify
67
68 Does limited verification of the structure of the queue.  If the
69 verification fails then a message is sent to stderr and the queue is
70 dumped as with the dump() method, and your program will exit.
71
72 =back
73
74 =head1 SEE ALSO
75
76 POE, POE::Queue, POE::Queue::Array
77
78 =head1 BUGS
79
80 None known.
81
82 Some possible improvements include:
83
84 =over
85
86 =item *
87
88 use a B-Tree for the queue (not a binary tree, a B-Tree), though this
89 would require a module rename.
90
91 =item *
92
93 use a custom hash instead of a HV for the id to priority mapping,
94 either glib's hash or convert to C++ and use the STL map.
95
96 =item *
97
98 some of the XS code could be optimized to do less work in scalar
99 context, pq_remove_items and pq_peek_items could avoid building all
100 those array refs.
101
102 =back
103
104 =head1 LICENSE
105
106 POE::XS::Queue::Array is licensed under the same terms as Perl itself.
107
108 =head1 AUTHOR
109
110 Tony Cook <tonyc@cpan.org>
111
112 =cut
113
114