NAME

DBIx::QuickORM::CAS::Result - Outcome of a compare-and-set operation.

DESCRIPTION

The value returned by $handle->cas and $row->cas. It reports whether the guarded update matched a row. In boolean context it is true only on a win, so if ($result) { ... } tells you the update went through.

A compare-and-set can end three ways: it won (exactly one row matched and was updated), it lost (no row matched, because the guard values had changed or the row was gone), or the outcome is unknown (the database driver could not report how many rows were affected). lost and unknown are both false in boolean context; use unknown to tell a genuine loss apart from a count the driver would not give.

A result from an async or aside handle starts out pending. ready reports, without blocking, whether the database has answered yet. Every other method (and boolean or string context) blocks until the answer is in, resolves once, and then behaves like a normal result. The row update is applied at resolution on a win. A synchronous result is already resolved, so ready is true and nothing ever blocks.

SYNOPSIS

my $result = $row->cas([qw/revision/], {body => $new_body});

if ($result) {
    # won: nobody else changed the row
}
elsif ($result->unknown) {
    # driver could not report the affected count
}
else {
    # lost: someone changed the guarded values, refetch and retry
}

# Async: poll instead of blocking.
my $pending = $handle->async->cas([qw/revision/], \%changes);
until ($pending->ready) { ... }
print "won\n" if $pending->won;

ATTRIBUTES

row

The row object the operation targeted. It carries the new values on a win and is left untouched on a loss or unknown outcome.

changes

The changes hashref that was applied (or attempted).

sth

resolver

Internal: the pending statement handle and the coderef that turns it into the affected-row count (applying the row update on a win). Both are consumed at resolution.

PUBLIC METHODS

$bool = $result->ready

True once the result is available: always true for a synchronous result, and for an async result once the database has answered. Does not block and does not apply the row update, but it does reap the statement once the database answers, so a real database error surfaces here rather than being deferred to a later method.

$int = $result->count

The affected row count: 1 on a win, 0 on a loss, or -1 when the driver could not report it. Resolves the result first (may block).

$bool = $result->won

$bool = $result->result

True only on a win (count is 1). This is also the boolean overload.

$bool = $result->lost

True on a loss (count is 0).

$bool = $result->unknown

True when the driver could not report the affected count (count is -1). The result is false, but this was not a confirmed loss.

$string = $result->state

One of 'won', 'lost', or 'unknown'. This is also the string overload.

PRIVATE METHODS

$result->_resolve

Block until the count is available, store it, and apply the row update on a win. A no-op once resolved.

SOURCE

The source code repository for DBIx::QuickORM can be found at https://github.com/exodist/DBIx-QuickORM.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/