=head1 NAME

RocksDB::MergeOperator - rocksdb::MergeOperator object

=head1 SYNOPSIS

  use RocksDB;

  my $handler = MyMergeOperator->new;
  my $db = RocksDB->new('/path/to/db', {
      merge_operator => RocksDB::MergeOperator->new($handler),
  });

=head1 DESCRIPTION

B<RocksDB::MergeOperator> is a utility class to make a rocksdb::MergeOperator object.

=head1 CONSTRUCTOR

=head2 C<< RocksDB::MergeOperator->new($handler :Object) :RocksDB::MergeOperator >>

Create and return a new RocksDB::MergeOperator object.

The $handler must respond to 'full_merge' and 'partial_merge'.

See 'HANDLER METHODS' section for more details.

=head1 HANDLER METHODS

=head2 C<< $handler->full_merge($key :Str, $existing_value :Maybe[Str], $operand_list :ArrayRef[Str]) :Str >>

Gives the client a way to express the read -> modify -> write semantics

$key: The key that's associated with this merge operation.
Client could multiplex the merge operator based on it
if the key space is partitioned and different subspaces
refer to different types of data which have different
merge operation semantics

$existing_value: undef indicates that the key does not exist before this op

$operand_list: the sequence of merge operations to apply.

Client is responsible for returning the merge result here.

All values passed in will be client-specific values. So if this method
raises an error, it is because client specified bad data or there was
internal corruption. This will be treated as an error by the library.

=head2 C<< $handler->partial_merge($key :Str, $left_operand :Str, $right_operand :Str) :Str >>

This function performs merge($left_operand, $right_operand)
when both the operands are themselves merge operation types
that you would have passed to a $db->merge() call in the same order
(i.e.: $db->merge($key,$left_op), followed by $db->merge($key,$right_op)).

PartialMerge should combine them into a single merge operation that is
saved return value.
Return value should be constructed such that a call to
$db->merge($key, $new_value) would yield the same result as a call
to $db->merge($key, $left_op) followed by $db->merge($key, $right_op).

If it is impossible or infeasible to combine the two operations,
raise an error (die). The library will internally keep track of the
operations, and apply them in the correct order once a base-value
(a Put/Delete/End-of-Database) is seen.

=head1 SEE ALSO

L<RocksDB>, L<RocksDB::AssociativeMergeOperator>

=head1 AUTHOR

Jiro Nishiguchi E<lt>jiro@cpan.orgE<gt>

=cut