view release on metacpan or  search on metacpan

lib/BusyBird/Timeline.pm  view on Meta::CPAN

            }
            foreach my $s (@$statuses) {
                $s->{busybird}{acked_at} = undef;
            }
            $timeline->put_statuses(
                mode => "update", statuses => $statuses,
                callback => sub {
                    my ($error, $num) = @_;
                    if($error) {
                        warn("error: $error");
                        return;
                    }
                    print "Updated $num statuses.\n";
                }
            );
        }
    );

    ## Delete all statuses
    $timeline->delete_statuses(
        ids => undef, callback => sub {
            my ($error, $num) = @_;
            if($error) {
                warn("error: $error");
                return;
            }
            print "Delete $num statuses.\n";
        }
    );

=head1 DESCRIPTION

L<BusyBird::Timeline> stores and manages a timeline, which is an ordered sequence of statuses.
You can add statuses to a timeline, and get statuses from the timeline.

This module uses L<BusyBird::Log> for logging.

=head2 Filters

You can set status filters to a timeline.
A status filter is a subroutine that is called when new statuses are added to the timeline
via C<add_statuses()> method.

Using status filters, you can modify or even drop the added statuses before they are
actually inserted to the timeline.
Status filters are executed in the same order as they are added.

L<BusyBird> comes with some pre-defined status filters. See L<BusyBird::Filter> for detail.

=head2 Status Storage

A timeline's statuses are actually saved in a L<BusyBird::StatusStorage> object.
When you create a timeline via C<new()> method, you have to specify a L<BusyBird::StatusStorage> object explicitly.

=head2 Callback-Style Methods

Some methods of L<BusyBird::Timeline> are callback-style, that is,
their results are not returned but given to the callback function you specify.

It depends on the underlying L<BusyBird::StatusStorage> object 
whether the callback-style methods are synchronous or asynchronous.
L<BusyBird::StatusStorage::SQLite>, for example, is synchronous.
If the status storage is synchronous, the callback is always called before the method returns.
If the status storage is asynchronous, it is possible for the method to return without calling the callback.
The callback will be called at a certain point later.

To handle callback-style methods, I recommend C<future_of()> function in L<BusyBird::Util>.
C<future_of()> function transforms callback-style methods into Future-style methods.

=head1 CLASS METHODS

=head2 $timeline = BusyBird::Timeline->new(%args)

Creates a new timeline.

You can also create a timeline via L<BusyBird::Main>'s C<timeline()> method.

Fields in C<%args> are as follows.

=over

=item C<name> => STRING (mandatory)

Specifies the name of the timeline.
If it includes Unicode characters, it must be a character string (decoded string), not a binary string (encoded string).

=item C<storage> => STATUS_STORAGE (mandatory)

Specifies a L<BusyBird::StatusStorage> object.
Statuses in C<$timeline> is saved to the C<storage>.

=back


=head1 OBJECT METHODS

=head2 $name = $timeline->name()

Returns the C<$timeline>'s name.

=head2 $timeline->add($statuses, [$callback])

=head2 $timeline->add_statuses(%args)

Adds new statuses to the C<$timeline>.

Note that statuses added by C<add_statuses()> method go through the C<$timeline>'s filters.
It is the filtered statuses that are actually inserted to the storage.

In addition to filtering, if statuses added to the C<$timeline> lack C<id> or C<created_at> field,
it automatically generates and sets these fields.
This auto-generation of IDs and timestamps are done after the filtering.

C<add()> method is a short-hand of C<< add_statuses(statuses => $statuses, callback => $callback) >>.

Fields in C<%args> are as follows.

=over

=item C<statuses> => {STATUS, ARRAYREF_OF_STATUSES} (mandatory)

Specifies a status object or an array-ref of status objects to be added.
See L<BusyBird::Manual::Status> about what status objects look like.

lib/BusyBird/Timeline.pm  view on Meta::CPAN

The key C<"total"> represents the total number of unacked statuses
in the C<$timeline>.

=back

For example, C<$unacked_counts> is structured like:

    $unacked_counts = {
        total => 3,
        0     => 1,
        1     => 2,
    };

This means there are 3 unacked statuses in total, one of which is in level 0,
and the rest is in level 2.


=head2 $timeline->contains(%args)

Checks if the given statuses (or IDs) are contained in the C<$timeline>.

Fields in C<%args> are as follows.

=over

=item C<query> => {STATUS, ID, ARRAYREF_OF_STATUSES_OR_IDS} (mandatory)

Specifies the statuses or IDs to be checked.

If it is a scalar, that value is treated as a status ID.
If it is a hash-ref, that object is treated as a status object.
If it is an array-ref,
elements in the array-ref are treated as status objects or IDs.
Status objects and IDs can be mixed in a single array-ref.

If some statuses in C<query> don't have their C<id> field, those statuses are always treated as "not contained" in the C<$timeline>.

If Status IDs include Unicode characters, they should be character strings (decoded strings), not binary strings (encoded strings).


=item C<callback> => CODEREF($error, $contained, $not_contained) (mandatory)

Specifies a subroutine reference that is called when the check has completed.

In success, C<callback> is called with three arguments (C<$error>, C<$contained>, C<$not_contained>).
C<$error> is C<undef>.
C<$contained> is an array-ref of given statuses or IDs that are contained in the C<$timeline>.
C<$not_contained> is an array-ref of given statuses or IDs that are NOT contained in the C<$timeline>.

In failure, C<$error> is a truthy value describing the error.

=back


=head2 $timeline->add_filter($filter, [$is_async])

Add a status filter to the C<$timeline>.

C<$filter> is a subroutine reference that is called upon added statuses.
C<$is_async> specifies whether the C<$filter> is synchronous or asynchronous.

L<BusyBird::Filter> may help you create common status filters.


B<< Synchronous Filter >>

If C<$is_async> is false, C<$filter> is a synchronous filter. It is called like

    $result_arrayref = $filter->($arrayref_of_statuses);

where C<$arrayref_of_statuses> is an array-ref of statuses that is injected to the filter.

C<$filter> must return an array-ref of statuses (C<$result_arrayref>), which is going to be passed to the next filter
(or the status storage if there is no next filter).
C<$result_arrayref> may be either C<$arrayref_of_statuses> or a new array-ref.
If C<$filter> returns anything other than an array-ref,
a warning is logged and C<$arrayref_of_statuses> is passed to the next.

B<< Asynchronous Filter >>

If C<$is_async> is true, C<$filter> is a asynchronous filter. It is called like

    $filter->($arrayref_of_statuses, $done);

where C<$done> is a subroutine reference that C<$filter> is supposed to call when it completes its task.
C<$filter> must pass the result array-ref of statuses to the C<$done> callback.

    $done->($result_arrayref)

B<< Examples >>

    ## Synchronous filter
    $timeline->add_filter(sub {
        my ($statuses) = @_;
        return [ grep { some_predicate($_) } @$statuses ];
    });
    
    ## Asynchronous filter
    $timeline->add_filter(sub {
        my ($statuses, $done) = @_;
        some_async_processing(
            statuses => $statuses,
            callback => sub {
                my ($results) = @_;
                $done->($results);
            }
        );
    }, 1);

=head2 $timeline->add_filter_async($filter)

Add an asynchronous status filter. This is equivalent to C<< $timeline->add_filter($filter, 1) >>.


=head2 $timeline->set_config($key1 => $value1, $key2 => $value2, ...)

Sets config parameters to the C<$timeline>.

C<$key1>, C<$key2>, ... are the keys for the config parameters, and
C<$value1>, C<$value2>, ... are the values for them.

See L<BusyBird::Manual::Config> for the list of config parameters.

=head2 $value = $timeline->get_config($key)

Returns the value of config parameter whose key is C<$key>.

If there is no config parameter associated with C<$key>, it returns C<undef>.



=head2 $watcher = $timeline->watch_unacked_counts(%args)

Watch updates of unacked counts in the C<$timeline>.

Fields in C<%args> are as follows.

=over

=item C<assumed> => HASHREF (mandatory)

Specifies the unacked counts that the caller assumes.

=item C<callback> => CODEREF ($error, $w, $unacked_counts) (mandatory)

Specifies the callback function that is called when the unacked counts given in C<assumed> argument
are different from the current unacked counts.

=back

In C<assumed> argument, caller must describe numbers of unacked statuses (i.e. unacked counts) for each status level and/or in total.
If the assumed unacked counts is different from the current unacked counts in C<$timeline>,
C<callback> subroutine reference is called with the current unacked counts (C<$unacked_counts>).
If the assumed unacked counts is the same as the current unacked counts, execution of C<callback> is delayed
until there is some difference between them.

Format of C<assumed> argument and C<%$unacked_counts> is the same as C<%$unacked_counts> returned by C<get_unacked_counts()> method.
See also the following example.

In success, the C<callback> is called with three arguments (C<$error>, C<$w>, C<$unacked_counts>).
C<$error> is C<undef>.
C<$w> is an L<BusyBird::Watcher> object representing this watch.
C<$unacked_counts> is a hash-ref describing the current unacked counts of the C<$timeline>.

In failure, C<$error> is a truthy value describing the error. C<$w> is an inactive L<BusyBird::Watcher>.

For example, 

    use Data::Dumper;
    
    my $watcher = $timeline->watch_unacked_counts(
        assumed => { total => 4, 1 => 2 },