/lib/pods/SDL/Time.pod

 1
 2=pod
 3
 4=head1 NAME
 5
 6SDL::Time - An SDL Perl extension for managing timers
 7
 8=head1 CATEGORY
 9
10Core
11
12=head1 SYNOPSIS
13
14 use warnings;
15 use strict;
16 
17 use threads;
18 use threads::shared;
19
20 use SDL::Time;
21
22 package foo;
23
24 use SDL ':all';
25
26 SDL::init(SDL_INIT_TIMER);
27
28 my $tick :shared = 0;
29 sub ticker { $tick++; warn $tick; return 100; }
30
31 package main;
32
33 my $id = SDL::Time::add_timer(100, 'foo::ticker');
34
35 sleep(2);
36
37 SDL::Time::remove_timer($id);
38
39=head1 METHODS
40
41=head2 add_timer
42
43 my $id = SDL::Timer::add_timer( $ms_interval, $callback );
44
45This runs in a separate thread and a cloned Perl thread.
46C<threads> and C<threads::shared> must be used to share any variables the timer uses.
47
48The C<$callback> function, specified with a string of the function's name, will be called after the milliseconds of C<$interval> have elapsed.
49The actual delay may be longer than specified depending on the underlying OS.
50The callback function is passed the current timer interval as well as the C<$interval> parameter and should return the next timer interval.
51If the return value from the callback is 0, the timer is cancelled; otherwise, the timer will continue to run.
52
53The timer callback function may run in a different thread to your main program, so it shouldn't call any functions from within itself.
54You may call SDL::push_event, however.
55
56C<SDL::Time::add_timer> returns the identifier value of the generated timer or undef on error.
57
58B<Note:> You must initialize (C<SDL::init>) the timer subsystem to use this function.
59
60=head2 remove_timer
61
62 SDL::Timer::remove_timer( $id );
63
64The other way to cancel a timer is to use C<SDL::Time::remove_timer> on the C<$id> of a timer.
65This ID is the return value of the C<SDL::Time::add_timer> function.
66
67C<SDL::Time::remove_timer> returns C<0> on success or C<-1> on error.
68
69=head1 AUTHORS
70
71See L<SDL/AUTHORS>.
72
73=cut