class CZMQ::FFI::Zhash

generic type-free hash container (simple) @note This class is 100% generated using zproject.

Public Class Methods

__new()
Alias for: new
create_finalizer_for(ptr) click to toggle source

@param ptr [::FFI::Pointer] @return [Proc]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 35
def self.create_finalizer_for(ptr)
  Proc.new do
    ptr_ptr = ::FFI::MemoryPointer.new :pointer
    ptr_ptr.write_pointer ptr
    ::CZMQ::FFI.zhash_destroy ptr_ptr
  end
end
free_fn() { |data| ... } click to toggle source

Create a new callback of the following type: Callback function for zhash_freefn method

typedef void (zhash_free_fn) (
    void *data);

@note WARNING: If your Ruby code doesn't retain a reference to the

FFI::Function object after passing it to a C function call,
it may be garbage collected while C still holds the pointer,
potentially resulting in a segmentation fault.
# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 85
def self.free_fn
  ::FFI::Function.new :void, [:pointer], blocking: true do |data|
    result = yield data
    result
  end
end
new(ptr, finalize = true) click to toggle source

Attaches the pointer ptr to this instance and defines a finalizer for it if necessary. @param ptr [::FFI::Pointer] @param finalize [Boolean]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 24
def initialize(ptr, finalize = true)
  @ptr = ptr
  if @ptr.null?
    @ptr = nil # Remove null pointers so we don't have to test for them.
  elsif finalize
    @finalizer = self.class.create_finalizer_for @ptr
    ObjectSpace.define_finalizer self, @finalizer
  end
end
new() click to toggle source

Create a new, empty hash container @return [CZMQ::Zhash]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 94
def self.new()
  ptr = ::CZMQ::FFI.zhash_new()
  __new ptr
end
Also aliased as: __new
test(verbose) click to toggle source

Self test of this class.

@param verbose [Boolean] @return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 374
def self.test(verbose)
  verbose = !(0==verbose||!verbose) # boolean
  result = ::CZMQ::FFI.zhash_test(verbose)
  result
end
unpack(frame) click to toggle source

Unpack binary frame into a new hash table. Packed data must follow format defined by zhash_pack. Hash table is set to autofree. An empty frame unpacks to an empty hash table. @param frame [Zframe, #__ptr] @return [CZMQ::Zhash]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 104
def self.unpack(frame)
  frame = frame.__ptr if frame
  ptr = ::CZMQ::FFI.zhash_unpack(frame)
  __new ptr
end

Public Instance Methods

__ptr() click to toggle source

Return internal pointer @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 48
def __ptr
  raise DestroyedError unless @ptr
  @ptr
end
Also aliased as: to_ptr
__ptr_give_ref() click to toggle source

Nullify internal pointer and return pointer pointer. @note This detaches the current instance from the native object

and thus makes it unusable.

@return [::FFI::MemoryPointer] the pointer pointing to a pointer

pointing to the native object
# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 59
def __ptr_give_ref
  raise DestroyedError unless @ptr
  ptr_ptr = ::FFI::MemoryPointer.new :pointer
  ptr_ptr.write_pointer @ptr
  __undef_finalizer if @finalizer
  @ptr = nil
  ptr_ptr
end
__undef_finalizer() click to toggle source

Undefines the finalizer for this object. @note Only use this if you need to and can guarantee that the native

object will be freed by other means.

@return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 71
def __undef_finalizer
  ObjectSpace.undefine_finalizer self
  @finalizer = nil
end
autofree() click to toggle source

Set hash for automatic value destruction. Note that this assumes that values are NULL-terminated strings. Do not use with different types.

@return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 363
def autofree()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_autofree(self_p)
  result
end
comment(format, *args) click to toggle source

Add a comment to hash table before saving to disk. You can add as many comment lines as you like. These comment lines are discarded when loading the file. If you use a null format, all comments are deleted.

@param format [String, to_s, nil] @param args [Array<Object>] see github.com/ffi/ffi/wiki/examples#using-varargs @return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 283
def comment(format, *args)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_comment(self_p, format, *args)
  result
end
cursor() click to toggle source

After a successful first/next method, returns the key for the item that was returned. This is a constant string that you may not modify or deallocate, and which lasts as long as the item in the hash. After an unsuccessful first/next, returns NULL.

@return [String]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 269
def cursor()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_cursor(self_p)
  result
end
delete(key) click to toggle source

Remove an item specified by key from the hash table. If there was no such item, this function does nothing.

@param key [String, to_s, nil] @return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 153
def delete(key)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_delete(self_p, key)
  result
end
destroy() click to toggle source

Destroy a hash container and all items in it

@return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 113
def destroy()
  return unless @ptr
  self_p = __ptr_give_ref
  result = ::CZMQ::FFI.zhash_destroy(self_p)
  result
end
dup() click to toggle source

Make copy of hash table; if supplied table is null, returns null. Does not copy items themselves. Rebuilds new table so may be slow on very large tables. NOTE: only works with item values that are strings since there's no other way to know how to duplicate the item value.

@return [Zhash]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 216
def dup()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_dup(self_p)
  result = Zhash.__new result, true
  result
end
first() click to toggle source

Simple iterator; returns first item in hash table, in no given order, or NULL if the table is empty. This method is simpler to use than the foreach() method, which is deprecated. To access the key for this item use zhash_cursor(). NOTE: do NOT modify the table while iterating.

@return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 241
def first()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_first(self_p)
  result
end
freefn(key, free_fn) click to toggle source

Set a free function for the specified hash table item. When the item is destroyed, the free function, if any, is called on that item. Use this when hash items are dynamically allocated, to ensure that you don't have memory leaks. You can pass 'free' or NULL as a free_fn. Returns the item, or NULL if there is no such item.

@param key [String, to_s, nil] @param free_fn [::FFI::Pointer, to_ptr] @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 193
def freefn(key, free_fn)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_freefn(self_p, key, free_fn)
  result
end
insert(key, item) click to toggle source

Insert item into hash table with specified key and item. If key is already present returns -1 and leaves existing item unchanged Returns 0 on success.

@param key [String, to_s, nil] @param item [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 127
def insert(key, item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_insert(self_p, key, item)
  result
end
keys() click to toggle source

Return keys for items in table

@return [Zlist]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 227
def keys()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_keys(self_p)
  result = Zlist.__new result, true
  result
end
load(filename) click to toggle source

Load hash table from a text file in name=value format; hash table must already exist. Hash values must printable strings; keys may not contain '=' character. Returns 0 if OK, else -1 if a file was not readable.

@param filename [String, to_s, nil] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 339
def load(filename)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_load(self_p, filename)
  result
end
lookup(key) click to toggle source

Return the item at the specified key, or null

@param key [String, to_s, nil] @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 164
def lookup(key)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_lookup(self_p, key)
  result
end
next() click to toggle source

Simple iterator; returns next item in hash table, in no given order, or NULL if the last item was already returned. Use this together with zhash_first() to process all items in a hash table. If you need the items in sorted order, use zhash_keys() and then zlist_sort(). To access the key for this item use zhash_cursor(). NOTE: do NOT modify the table while iterating.

@return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 256
def next()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_next(self_p)
  result
end
null?() click to toggle source

@return [Boolean]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 43
def null?
  !@ptr or @ptr.null?
end
pack() click to toggle source

Serialize hash table to a binary frame that can be sent in a message. The packed format is compatible with the 'dictionary' type defined in rfc.zeromq.org/spec:35/FILEMQ, and implemented by zproto:

; A list of name/value pairs
dictionary      = dict-count *( dict-name dict-value )
dict-count      = number-4
dict-value      = longstr
dict-name       = string

; Strings are always length + text contents
longstr         = number-4 *VCHAR
string          = number-1 *VCHAR

; Numbers are unsigned integers in network byte order
number-1        = 1OCTET
number-4        = 4OCTET

Comments are not included in the packed data. Item values MUST be strings.

@return [Zframe]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 312
def pack()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_pack(self_p)
  result = Zframe.__new result, true
  result
end
refresh() click to toggle source

When a hash table was loaded from a file by zhash_load, this method will reload the file if it has been modified since, and is “stable”, i.e. not still changing. Returns 0 if OK, -1 if there was an error reloading the file.

@return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 352
def refresh()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_refresh(self_p)
  result
end
rename(old_key, new_key) click to toggle source

Reindexes an item from an old key to a new key. If there was no such item, does nothing. Returns 0 if successful, else -1.

@param old_key [String, to_s, nil] @param new_key [String, to_s, nil] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 177
def rename(old_key, new_key)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_rename(self_p, old_key, new_key)
  result
end
save(filename) click to toggle source

Save hash table to a text file in name=value format. Hash values must be printable strings; keys may not contain '=' character. Returns 0 if OK, else -1 if a file error occurred.

@param filename [String, to_s, nil] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 326
def save(filename)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_save(self_p, filename)
  result
end
size() click to toggle source

Return the number of keys/items in the hash table

@return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 203
def size()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_size(self_p)
  result
end
to_ptr()

So external Libraries can just pass the Object to a FFI function which expects a :pointer

Alias for: __ptr
update(key, item) click to toggle source

Update item into hash table with specified key and item. If key is already present, destroys old item and inserts new one. Use free_fn method to ensure deallocator is properly called on item.

@param key [String, to_s, nil] @param item [::FFI::Pointer, to_ptr] @return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zhash.rb, line 141
def update(key, item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_update(self_p, key, item)
  result
end