class TkrzwRPC::Iterator

Iterator for each record. An iterator is made by the “make_iterator” method of DBM. Every unused iterator object should be destructed explicitly by the “destruct” method to free resources.

Public Class Methods

new(dbm) click to toggle source

Initializes the iterator.

@param dbm The database to scan.

# File tkrzw_rpc.rb, line 1211
def initialize(dbm)
  if not dbm.channel
    raise StatusException.new(Status.new(Status.PRECONDITION_ERROR, "not opened connection"))
  end
  @dbm = dbm
  @req_it = RequestIterator.new
  begin
    @res_it = dbm.stub.iterate(@req_it.each_item)
  rescue GRPC::BadStatus
    @dbm = nil
    @req_it = nil
  end
end

Public Instance Methods

destruct() click to toggle source

Releases the resource explicitly.

# File tkrzw_rpc.rb, line 1226
def destruct
  @req_it.request = nil
  @req_it.event.set
  @dbm = nil
  @req_it = nil
  @res_it = nil
end

first() click to toggle source

Initializes the iterator to indicate the first record.

@return The result status.

Even if there's no record, the operation doesn't fail.

# File tkrzw_rpc.rb, line 1237
def first
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_FIRST
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

get(status=nil) click to toggle source

Gets the key and the value of the current record of the iterator.

@param status A status object to which the result status is assigned. It can be omitted.
@return A tuple of The key and the value of the current record. On failure, nil is returned.

# File tkrzw_rpc.rb, line 1373
def get(status=nil)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_GET
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  if status
    set_status_from_proto(status, response.status)
  end
  if response.status.code == Status::SUCCESS
    if @dbm.encoding
      return [response.key.dup.force_encoding(@dbm.encoding),
              response.value.dup.force_encoding(@dbm.encoding)]
    end
    return [response.key, response.value]
  end
  nil
end

get_key(status=nil) click to toggle source

Gets the key of the current record.

@param status A status object to which the result status is assigned. It can be omitted.
@return The key of the current record or nil on failure.

# File tkrzw_rpc.rb, line 1401
def get_key(status=nil)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_GET
  request.omit_value = true
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  if status
    set_status_from_proto(status, response.status)
  end
  if response.status.code == Status::SUCCESS
    if @dbm.encoding
      return response.key.dup.force_encoding(@encoding)
    end
    return response.key
  end
  nil
end

get_value(status=nil) click to toggle source

Gets the value of the current record.

@param status A status object to which the result status is assigned. It can be omitted.
@return The value of the current record or nil on failure.

# File tkrzw_rpc.rb, line 1429
def get_value(status=nil)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_GET
  request.omit_key = true
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  if status
    set_status_from_proto(status, response.status)
  end
  if response.status.code == Status::SUCCESS
    if @dbm.encoding
      return response.value.dup.force_encoding(@encoding)
    end
    return response.value
  end
  nil
end

inspect() click to toggle source

Returns a string representation of the object.

@return The string representation of the object.

# File tkrzw_rpc.rb, line 1527
def inspect
  expr = @dbm.channel ? "connected" : "not connected"
  "#<TkrzwRPC::Iterator: 0x" + object_id.to_s(16) + ": " + expr + ">"
end

jump(key) click to toggle source

Initializes the iterator to indicate a specific record.

@param key The key of the record to look for.
@return The result status.

Ordered databases can support “lower bound” jump; If there's no record with the same key, the iterator refers to the first record whose key is greater than the given key. The operation fails with unordered databases if there's no record with the same key.

# File tkrzw_rpc.rb, line 1274
def jump(key)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_JUMP
  request.key = make_string(key)
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

jump_lower(key, inclusive=false) click to toggle source

Initializes the iterator to indicate the last record whose key is lower than a given key.

@param key The key to compare with.
@param inclusive If true, the considtion is inclusive: equal to or lower than the key.
@return The result status.

Even if there's no matching record, the operation doesn't fail. This method is suppoerted only by ordered databases.

# File tkrzw_rpc.rb, line 1295
def jump_lower(key, inclusive=false)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_JUMP_LOWER
  request.key = make_string(key)
  request.jump_inclusive = inclusive
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

jump_upper(key, inclusive=false) click to toggle source

Initializes the iterator to indicate the first record whose key is upper than a given key.

@param key The key to compare with.
@param inclusive If true, the considtion is inclusive: equal to or upper than the key.
@return The result status.

Even if there's no matching record, the operation doesn't fail. This method is suppoerted only by ordered databases.

# File tkrzw_rpc.rb, line 1317
def jump_upper(key, inclusive=false)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_JUMP_UPPER
  request.key = make_string(key)
  request.jump_inclusive = inclusive
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

last() click to toggle source

Initializes the iterator to indicate the last record.

@return The result status.

Even if there's no record, the operation doesn't fail. This method is suppoerted only by ordered databases.

# File tkrzw_rpc.rb, line 1255
def last
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_LAST
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

next() click to toggle source

Moves the iterator to the next record.

@return The result status.

If the current record is missing, the operation fails. Even if there's no next record, the operation doesn't fail.

# File tkrzw_rpc.rb, line 1337
def next
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_NEXT
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

previous() click to toggle source

Moves the iterator to the previous record.

@return The result status.

If the current record is missing, the operation fails. Even if there's no previous record, the operation doesn't fail. This method is suppoerted only by ordered databases.

# File tkrzw_rpc.rb, line 1355
def previous
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_PREVIOUS
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

remove() click to toggle source

Removes the current record.

@return The result status.

# File tkrzw_rpc.rb, line 1475
def remove
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_REMOVE
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

set(value) click to toggle source

Sets the value of the current record.

@param value The value of the record.
@return The result status.

# File tkrzw_rpc.rb, line 1457
def set(value)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_SET
  request.value = value
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  return make_status_from_proto(response.status)
end

step(status=nil) click to toggle source

Gets the current record and moves the iterator to the next record.

@param status A status object to which the result status is assigned. It can be omitted.
@return A tuple of The key and the value of the current record. On failure, nil is returned.

# File tkrzw_rpc.rb, line 1493
def step(status=nil)
  request = IterateRequest.new
  request.dbm_index = @dbm.dbm_index
  request.operation = IterateRequest::OpType::OP_STEP
  begin
    @req_it.request = request
    @req_it.event.set
    response = @res_it.next
    @req_it.request = nil
  rescue GRPC::BadStatus => error
    return Status.new(Status::NETWORK_ERROR, str_grpc_error(error))
  end
  if status
    set_status_from_proto(status, response.status)
  end
  if response.status.code == Status::SUCCESS
    if @dbm.encoding
      return [response.key.dup.force_encoding(@dbm.encoding),
              response.value.dup.force_encoding(@dbm.encoding)]
    end
    return [response.key, response.value]
  end
  nil
end

to_s() click to toggle source

Returns a string representation of the content.

@return The string representation of the content.

# File tkrzw_rpc.rb, line 1520
def to_s
  expr = @dbm.channel ? "connected" : "not connected"
  "Iterator: 0x" + object_id.to_s(16) + ": " + expr
end