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