root/perl/lib/JLog/Reader.pm

Revision 81ac86a15e3940ff0b787698853fb6a6157f800b, 3.0 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 7 years ago)

initial import with Ecelerity bits removed and some autoconf glue added in. Could certainly use some work on the build/install. Needs shared lib support for multiple platforms

  • Property mode set to 100644
Line 
1 package JLog::Reader;
2
3 require DynaLoader;
4
5 use JLog;
6 use strict;
7
8 use vars qw/@ISA/;
9
10 @ISA = qw(Exporter DynaLoader JLog);
11
12 1;
13 __END__
14
15 =head1 NAME
16
17 JLog::Reader - Perl extension for reading to a jlog journal.
18
19 =head1 SUMMARY
20
21   use JLog::Reader;
22   # create a new reader off the log directory
23   $r = JLog::Reader->new($log);
24   # open the log as the indicated subscriber
25   $r->open($subscriber);
26   while(my $line = $r->read) {
27     # work with $line
28   }
29   # mark the seen records as read
30   $r->checkpoint;
31
32 or
33
34   use JLog::Reader;
35   $r = JLog::Reader->new($log);
36   $r->open($subscriber);
37   # mark lines read as they are pulled off the queue
38   $r->auto_checkpoint(1);
39   while(my $line = $r->read) {
40     # work with $line
41   }
42
43
44 =head1 DESCRIPTION
45
46 JLog::Reader allows you to access a jlog queue for reader.
47
48 =head1 INTERFACE
49
50 =head2 Constructor
51
52 =head3 new
53
54   $w = JLog::Reader->new( $path_to_jlog, [ $flags [, $size ] ] );
55
56 Instantiates a JLog writer object associated with the JLog directory.
57
58 =over 4
59
60 =item $path_to_jlog
61
62 The directory for the JLog queue.
63
64 =item $flags
65
66 Optional flags, from 'Fcntl'.  The default is O_CREAT.
67
68 =item $size
69
70 Optional size of the individual journal files.
71
72 =back
73
74 =head2 Subscriber Management
75
76 These functions are inherited from JLog
77
78 =head3 add_subscriber
79
80   $w->add_subscriber( $name, [ $flag ] );
81
82 Add a subscriber to the JLog queue.
83
84 =over 4
85
86 =item $name
87
88 The name of the subscriber.
89
90 =item $flag
91
92 An optional flag dictating where the subscriber should be marked interested
93 from.  The default is JLog::JLOG_BEGIN.  The other available option is
94 JLog::JLOG_END.
95
96 =back
97
98 =head3 remove_subscriber
99
100   $w->remove_subscriber ( $name );
101
102 Remove a subscriber to the JLog queue.
103
104 =over 4
105
106 =item $name
107
108 The name of the subscriber.
109
110 =back
111
112 =head2 Reading From The Queue
113
114 =head3 open
115
116   $w->open( $subscriber_name );
117
118 Opens the JLog for reading.
119
120 =over 4
121
122 =item $subscriber_name
123
124 The name we want to subscribe under.  This must previously have been
125 registered as a log subscriber via add_subscriber().
126
127 =back
128
129 =head3 read
130
131   $message = $w->read;
132
133 Read the next message from the JLog queue.
134
135 =head3 checkpoint
136
137   $r->checkpoint;
138
139 Checkpoint your read.  This will notify the JLog that you have successfully
140 read logs up to this point.  If all registered subscribers have read to
141 a certain point, the JLog system can remove the underlying data for the
142 read messages.
143
144 =head2 auto_checkpoint( [ $val ] )
145
146 Returns (and optionally sets) the auto_checkpoint property.  With
147 auto-checkpointing enabled, JLog::Reader will automatically
148 checkpoint whenever you call read().
149
150 =over 4
151
152 =item $val
153
154 The value you wish to set auto_checkpointing to.
155
156 =back
157
158 =head2 Internals
159
160 =head3 alter_journal_size
161
162   $r->alter_journal_size( $size );
163
164 Set the size of the individual journal files.
165
166 =over 4
167
168 =item $size
169
170 The desired size in bytes.
171
172 =back
173
174 =head3 raw_size
175
176   $size = $r->raw_size;
177
178 The size of the existing journal (including checkpointed but unpurged messages
179 in the current journal file), in bytes.
180
181 =head1 SEE ALSO
182
183 JLog
184 JLog::Writer
185
186 =head1 COPYRIGHT
187
188 Copyright (C) 2006 by OmniTI, Inc.
189
190 =cut
Note: See TracBrowser for help on using the browser.