4f3fcf36f17b44fb5327de0f39fb6d89135ed5bc
[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_02';
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 sub CLONE_SKIP { 1 }
35
36 # everything else is XS
37 1;
38
39 __END__
40
41 =head1 NAME
42
43 POE::XS::Queue::Array - an XS implementation of POE::Queue::Array.
44
45 =head1 SYNOPSIS
46
47 See POE::Queue.
48
49 =head1 DESCRIPTION
50
51 This class is an implementation of the abstract POE::Queue interface.
52 It implements a priority queue using C, with an XS interface supplied.
53
54 The current implementation could use some optimization, especially for
55 large queues.
56
57 Please see the POE::Queue documentation, which explains this one's
58 functions, features, and behavior.
59
60 The following extra methods are added beyond POE::Queue::Array:
61
62 =over
63
64 =item dump
65
66 Dumps the internal structure of the queue to stderr.
67
68 =item verify
69
70 Does limited verification of the structure of the queue.  If the
71 verification fails then a message is sent to stderr and the queue is
72 dumped as with the dump() method, and your program will exit.
73
74 =back
75
76 =head1 SEE ALSO
77
78 POE, POE::Queue, POE::Queue::Array
79
80 =head1 BUGS
81
82 None known.
83
84 Some possible improvements include:
85
86 =over
87
88 =item *
89
90 use a B-Tree for the queue (not a binary tree, a B-Tree), though this
91 would require a module rename.
92
93 =item *
94
95 use a custom hash instead of a HV for the id to priority mapping,
96 either glib's hash or convert to C++ and use the STL map.
97
98 =item *
99
100 some of the XS code could be optimized to do less work in scalar
101 context, pq_remove_items and pq_peek_items could avoid building all
102 those array refs.
103
104 =back
105
106 =head1 LICENSE
107
108 POE::XS::Queue::Array is licensed under the same terms as Perl itself.
109
110 =head1 AUTHOR
111
112 Tony Cook <tonyc@cpan.org>
113
114 =cut
115
116