Class: CZMQ::FFI::Zhash

Inherits:
Object
  • Object
show all
Defined in:
lib/czmq-ffi-gen/czmq/ffi/zhash.rb

Overview

Note:

This class is 100% generated using zproject.

generic type-free hash container (simple)

Defined Under Namespace

Classes: DestroyedError

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ptr, finalize = true) ⇒ Zhash

Attaches the pointer ptr to this instance and defines a finalizer for it if necessary.

Parameters:

  • ptr (::FFI::Pointer)
  • finalize (Boolean) (defaults to: true) 


24
25
26
27
28
29
30
31
32
 
# 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

Class Method Details

.__new ⇒ Object 



18
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 18

alias :__new :new

.create_finalizer_for(ptr) ⇒ Proc

Parameters:

  • ptr (::FFI::Pointer)

Returns:

  • (Proc) 


35
36
37
38
39
40
41
42
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 35

def self.create_finalizer_for(ptr)
  ptr_ptr = ::FFI::MemoryPointer.new :pointer

  Proc.new do
    ptr_ptr.write_pointer ptr
    ::CZMQ::FFI.zhash_destroy ptr_ptr
  end
end

.free_fn ⇒ Object

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.

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

typedef void (zhash_free_fn) (
    void *data);



86
87
88
89
90
91
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 86

def self.free_fn
  ::FFI::Function.new :void, [:pointer], blocking: true do |data|
    result = yield data
    result
  end
end

.new ⇒ CZMQ::Zhash

Create a new, empty hash container

Returns:

  • (CZMQ::Zhash) 


95
96
97
98
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 95

def self.new()
  ptr = ::CZMQ::FFI.zhash_new()
  __new ptr
end

.test(verbose) ⇒ void

This method returns an undefined value.

Self test of this class.

Parameters:

  • verbose (Boolean) 


375
376
377
378
379
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 375

def self.test(verbose)
  verbose = !(0==verbose||!verbose) # boolean
  result = ::CZMQ::FFI.zhash_test(verbose)
  result
end

.unpack(frame) ⇒ CZMQ::Zhash

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.

Parameters:

Returns:

  • (CZMQ::Zhash) 


105
106
107
108
109
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 105

def self.unpack(frame)
  frame = frame.__ptr if frame
  ptr = ::CZMQ::FFI.zhash_unpack(frame)
  __new ptr
end

Instance Method Details

#__ptr ⇒ ::FFI::Pointer Also known as: to_ptr

Return internal pointer

Returns:

  • (::FFI::Pointer)

Raises:



49
50
51
52
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 49

def __ptr
  raise DestroyedError unless @ptr
  @ptr
end

#__ptr_give_ref ⇒ ::FFI::MemoryPointer

Note:

This detaches the current instance from the native object and thus makes it unusable.

Nullify internal pointer and return pointer pointer.

Returns:

  • (::FFI::MemoryPointer) —

    the pointer pointing to a pointer pointing to the native object

Raises:



60
61
62
63
64
65
66
67
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 60

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 ⇒ void

Note:

Only use this if you need to and can guarantee that the native object will be freed by other means.

This method returns an undefined value.

Undefines the finalizer for this object.



72
73
74
75
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 72

def __undef_finalizer
  ObjectSpace.undefine_finalizer self
  @finalizer = nil
end

#autofree ⇒ void

This method returns an undefined value.

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

Raises:



364
365
366
367
368
369
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 364

def autofree()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_autofree(self_p)
  result
end

#comment(format, *args) ⇒ void

This method returns an undefined value.

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.

Parameters:

Raises:



284
285
286
287
288
289
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 284

def comment(format, *args)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_comment(self_p, format, *args)
  result
end

#cursor ⇒ String

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.

Returns:

  • (String)

Raises:



270
271
272
273
274
275
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 270

def cursor()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_cursor(self_p)
  result
end

#delete(key) ⇒ void

This method returns an undefined value.

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

Parameters:

  • key (String, #to_s, nil)

Raises:



154
155
156
157
158
159
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 154

def delete(key)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_delete(self_p, key)
  result
end

#destroy ⇒ void

This method returns an undefined value.

Destroy a hash container and all items in it



114
115
116
117
118
119
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 114

def destroy()
  return unless @ptr
  self_p = __ptr_give_ref
  result = ::CZMQ::FFI.zhash_destroy(self_p)
  result
end

#dup ⇒ Zhash

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.

Returns:

Raises:



217
218
219
220
221
222
223
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 217

def dup()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_dup(self_p)
  result = Zhash.__new result, true
  result
end

#first ⇒ ::FFI::Pointer

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.

Returns:

  • (::FFI::Pointer)

Raises:



242
243
244
245
246
247
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 242

def first()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_first(self_p)
  result
end

#freefn(key, free_fn) ⇒ ::FFI::Pointer

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.

Parameters:

  • key (String, #to_s, nil)
  • free_fn (::FFI::Pointer, #to_ptr)

Returns:

  • (::FFI::Pointer)

Raises:



194
195
196
197
198
199
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 194

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) ⇒ Integer

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.

Parameters:

  • key (String, #to_s, nil)
  • item (::FFI::Pointer, #to_ptr)

Returns:

  • (Integer)

Raises:



128
129
130
131
132
133
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 128

def insert(key, item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_insert(self_p, key, item)
  result
end

#keys ⇒ Zlist

Return keys for items in table

Returns:

Raises:



228
229
230
231
232
233
234
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 228

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) ⇒ Integer

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.

Parameters:

  • filename (String, #to_s, nil)

Returns:

  • (Integer)

Raises:



340
341
342
343
344
345
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 340

def load(filename)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_load(self_p, filename)
  result
end

#lookup(key) ⇒ ::FFI::Pointer

Return the item at the specified key, or null

Parameters:

  • key (String, #to_s, nil)

Returns:

  • (::FFI::Pointer)

Raises:



165
166
167
168
169
170
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 165

def lookup(key)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_lookup(self_p, key)
  result
end

#next ⇒ ::FFI::Pointer

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.

Returns:

  • (::FFI::Pointer)

Raises:



257
258
259
260
261
262
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 257

def next()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_next(self_p)
  result
end

#null? ⇒ Boolean

Returns:

  • (Boolean) 


44
45
46
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 44

def null?
  !@ptr or @ptr.null?
end

#pack ⇒ Zframe

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.

Returns:

Raises:



313
314
315
316
317
318
319
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 313

def pack()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_pack(self_p)
  result = Zframe.__new result, true
  result
end

#refresh ⇒ Integer

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.

Returns:

  • (Integer)

Raises:



353
354
355
356
357
358
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 353

def refresh()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_refresh(self_p)
  result
end

#rename(old_key, new_key) ⇒ Integer

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.

Parameters:

  • old_key (String, #to_s, nil)
  • new_key (String, #to_s, nil)

Returns:

  • (Integer)

Raises:



178
179
180
181
182
183
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 178

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) ⇒ Integer

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.

Parameters:

  • filename (String, #to_s, nil)

Returns:

  • (Integer)

Raises:



327
328
329
330
331
332
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 327

def save(filename)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_save(self_p, filename)
  result
end

#size ⇒ Integer

Return the number of keys/items in the hash table

Returns:

  • (Integer)

Raises:



204
205
206
207
208
209
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 204

def size()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_size(self_p)
  result
end

#update(key, item) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • key (String, #to_s, nil)
  • item (::FFI::Pointer, #to_ptr)

Raises:



142
143
144
145
146
147
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zhash.rb', line 142

def update(key, item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zhash_update(self_p, key, item)
  result
end