1################################################################################ 2# THIS FILE IS 100% GENERATED BY ZPROJECT; DO NOT EDIT EXCEPT EXPERIMENTALLY # 3# Read the zproject/README.md for information about making permanent changes. # 4################################################################################ 5 6module CZMQ 7 module FFI 8 9 # extended generic type-free hash container 10 # @note This class is 100% generated using zproject. 11 class Zhashx 12 # Raised when one tries to use an instance of {Zhashx} after 13 # the internal pointer to the native object has been nullified. 14 class DestroyedError < RuntimeError; end 15 16 # Boilerplate for self pointer, initializer, and finalizer 17 class << self 18 alias :__new :new 19 end 20 # Attaches the pointer _ptr_ to this instance and defines a finalizer for 21 # it if necessary. 22 # @param ptr [::FFI::Pointer] 23 # @param finalize [Boolean] 24 def initialize(ptr, finalize = true) 25 @ptr = ptr 26 if @ptr.null? 27 @ptr = nil # Remove null pointers so we don't have to test for them. 28 elsif finalize 29 @finalizer = self.class.create_finalizer_for @ptr 30 ObjectSpace.define_finalizer self, @finalizer 31 end 32 end 33 # @param ptr [::FFI::Pointer] 34 # @return [Proc] 35 def self.create_finalizer_for(ptr) 36 Proc.new do 37 ptr_ptr = ::FFI::MemoryPointer.new :pointer 38 ptr_ptr.write_pointer ptr 39 ::CZMQ::FFI.zhashx_destroy ptr_ptr 40 end 41 end 42 # @return [Boolean] 43 def null? 44 !@ptr or @ptr.null? 45 end 46 # Return internal pointer 47 # @return [::FFI::Pointer] 48 def __ptr 49 raise DestroyedError unless @ptr 50 @ptr 51 end 52 # So external Libraries can just pass the Object to a FFI function which expects a :pointer 53 alias_method :to_ptr, :__ptr 54 # Nullify internal pointer and return pointer pointer. 55 # @note This detaches the current instance from the native object 56 # and thus makes it unusable. 57 # @return [::FFI::MemoryPointer] the pointer pointing to a pointer 58 # pointing to the native object 59 def __ptr_give_ref 60 raise DestroyedError unless @ptr 61 ptr_ptr = ::FFI::MemoryPointer.new :pointer 62 ptr_ptr.write_pointer @ptr 63 __undef_finalizer if @finalizer 64 @ptr = nil 65 ptr_ptr 66 end 67 # Undefines the finalizer for this object. 68 # @note Only use this if you need to and can guarantee that the native 69 # object will be freed by other means. 70 # @return [void] 71 def __undef_finalizer 72 ObjectSpace.undefine_finalizer self 73 @finalizer = nil 74 end 75 76 # Create a new callback of the following type: 77 # Destroy an item 78 # typedef void (zhashx_destructor_fn) ( 79 # void **item); 80 # 81 # @note WARNING: If your Ruby code doesn't retain a reference to the 82 # FFI::Function object after passing it to a C function call, 83 # it may be garbage collected while C still holds the pointer, 84 # potentially resulting in a segmentation fault. 85 def self.destructor_fn 86 ::FFI::Function.new :void, [:pointer], blocking: true do |item| 87 result = yield item 88 result 89 end 90 end 91 92 # Create a new callback of the following type: 93 # Duplicate an item 94 # typedef void * (zhashx_duplicator_fn) ( 95 # const void *item); 96 # 97 # @note WARNING: If your Ruby code doesn't retain a reference to the 98 # FFI::Function object after passing it to a C function call, 99 # it may be garbage collected while C still holds the pointer, 100 # potentially resulting in a segmentation fault. 101 def self.duplicator_fn 102 ::FFI::Function.new :pointer, [:pointer], blocking: true do |item| 103 result = yield item 104 result 105 end 106 end 107 108 # Create a new callback of the following type: 109 # Compare two items, for sorting 110 # typedef int (zhashx_comparator_fn) ( 111 # const void *item1, const void *item2); 112 # 113 # @note WARNING: If your Ruby code doesn't retain a reference to the 114 # FFI::Function object after passing it to a C function call, 115 # it may be garbage collected while C still holds the pointer, 116 # potentially resulting in a segmentation fault. 117 def self.comparator_fn 118 ::FFI::Function.new :int, [:pointer, :pointer], blocking: true do |item1, item2| 119 result = yield item1, item2 120 result = Integer(result) 121 result 122 end 123 end 124 125 # Create a new callback of the following type: 126 # Destroy an item. 127 # typedef void (zhashx_free_fn) ( 128 # void *data); 129 # 130 # @note WARNING: If your Ruby code doesn't retain a reference to the 131 # FFI::Function object after passing it to a C function call, 132 # it may be garbage collected while C still holds the pointer, 133 # potentially resulting in a segmentation fault. 134 def self.free_fn 135 ::FFI::Function.new :void, [:pointer], blocking: true do |data| 136 result = yield data 137 result 138 end 139 end 140 141 # Create a new callback of the following type: 142 # Hash function for keys. 143 # typedef size_t (zhashx_hash_fn) ( 144 # const void *key); 145 # 146 # @note WARNING: If your Ruby code doesn't retain a reference to the 147 # FFI::Function object after passing it to a C function call, 148 # it may be garbage collected while C still holds the pointer, 149 # potentially resulting in a segmentation fault. 150 def self.hash_fn 151 ::FFI::Function.new :size_t, [:pointer], blocking: true do |key| 152 result = yield key 153 result = Integer(result) 154 result 155 end 156 end 157 158 # Create a new callback of the following type: 159 # Serializes an item to a longstr. 160 # The caller takes ownership of the newly created object. 161 # typedef char * (zhashx_serializer_fn) ( 162 # const void *item); 163 # 164 # @note WARNING: If your Ruby code doesn't retain a reference to the 165 # FFI::Function object after passing it to a C function call, 166 # it may be garbage collected while C still holds the pointer, 167 # potentially resulting in a segmentation fault. 168 def self.serializer_fn 169 ::FFI::Function.new :pointer, [:pointer], blocking: true do |item| 170 result = yield item 171 result 172 end 173 end 174 175 # Create a new callback of the following type: 176 # Deserializes a longstr into an item. 177 # The caller takes ownership of the newly created object. 178 # typedef void * (zhashx_deserializer_fn) ( 179 # const char *item_str); 180 # 181 # @note WARNING: If your Ruby code doesn't retain a reference to the 182 # FFI::Function object after passing it to a C function call, 183 # it may be garbage collected while C still holds the pointer, 184 # potentially resulting in a segmentation fault. 185 def self.deserializer_fn 186 ::FFI::Function.new :pointer, [:string], blocking: true do |item_str| 187 result = yield item_str 188 result 189 end 190 end 191 192 # Create a new, empty hash container 193 # @return [CZMQ::Zhashx] 194 def self.new() 195 ptr = ::CZMQ::FFI.zhashx_new() 196 __new ptr 197 end 198 199 # Unpack binary frame into a new hash table. Packed data must follow format 200 # defined by zhashx_pack. Hash table is set to autofree. An empty frame 201 # unpacks to an empty hash table. 202 # @param frame [Zframe, #__ptr] 203 # @return [CZMQ::Zhashx] 204 def self.unpack(frame) 205 frame = frame.__ptr if frame 206 ptr = ::CZMQ::FFI.zhashx_unpack(frame) 207 __new ptr 208 end 209 210 # Same as unpack but uses a user-defined deserializer function to convert 211 # a longstr back into item format. 212 # @param frame [Zframe, #__ptr] 213 # @param deserializer [::FFI::Pointer, #to_ptr] 214 # @return [CZMQ::Zhashx] 215 def self.unpack_own(frame, deserializer) 216 frame = frame.__ptr if frame 217 ptr = ::CZMQ::FFI.zhashx_unpack_own(frame, deserializer) 218 __new ptr 219 end 220 221 # Destroy a hash container and all items in it 222 # 223 # @return [void] 224 def destroy() 225 return unless @ptr 226 self_p = __ptr_give_ref 227 result = ::CZMQ::FFI.zhashx_destroy(self_p) 228 result 229 end 230 231 # Insert item into hash table with specified key and item. 232 # If key is already present returns -1 and leaves existing item unchanged 233 # Returns 0 on success. 234 # 235 # @param key [::FFI::Pointer, #to_ptr] 236 # @param item [::FFI::Pointer, #to_ptr] 237 # @return [Integer] 238 def insert(key, item) 239 raise DestroyedError unless @ptr 240 self_p = @ptr 241 result = ::CZMQ::FFI.zhashx_insert(self_p, key, item) 242 result 243 end 244 245 # Update or insert item into hash table with specified key and item. If the 246 # key is already present, destroys old item and inserts new one. If you set 247 # a container item destructor, this is called on the old value. If the key 248 # was not already present, inserts a new item. Sets the hash cursor to the 249 # new item. 250 # 251 # @param key [::FFI::Pointer, #to_ptr] 252 # @param item [::FFI::Pointer, #to_ptr] 253 # @return [void] 254 def update(key, item) 255 raise DestroyedError unless @ptr 256 self_p = @ptr 257 result = ::CZMQ::FFI.zhashx_update(self_p, key, item) 258 result 259 end 260 261 # Remove an item specified by key from the hash table. If there was no such 262 # item, this function does nothing. 263 # 264 # @param key [::FFI::Pointer, #to_ptr] 265 # @return [void] 266 def delete(key) 267 raise DestroyedError unless @ptr 268 self_p = @ptr 269 result = ::CZMQ::FFI.zhashx_delete(self_p, key) 270 result 271 end 272 273 # Delete all items from the hash table. If the key destructor is 274 # set, calls it on every key. If the item destructor is set, calls 275 # it on every item. 276 # 277 # @return [void] 278 def purge() 279 raise DestroyedError unless @ptr 280 self_p = @ptr 281 result = ::CZMQ::FFI.zhashx_purge(self_p) 282 result 283 end 284 285 # Return the item at the specified key, or null 286 # 287 # @param key [::FFI::Pointer, #to_ptr] 288 # @return [::FFI::Pointer] 289 def lookup(key) 290 raise DestroyedError unless @ptr 291 self_p = @ptr 292 result = ::CZMQ::FFI.zhashx_lookup(self_p, key) 293 result 294 end 295 296 # Reindexes an item from an old key to a new key. If there was no such 297 # item, does nothing. Returns 0 if successful, else -1. 298 # 299 # @param old_key [::FFI::Pointer, #to_ptr] 300 # @param new_key [::FFI::Pointer, #to_ptr] 301 # @return [Integer] 302 def rename(old_key, new_key) 303 raise DestroyedError unless @ptr 304 self_p = @ptr 305 result = ::CZMQ::FFI.zhashx_rename(self_p, old_key, new_key) 306 result 307 end 308 309 # Set a free function for the specified hash table item. When the item is 310 # destroyed, the free function, if any, is called on that item. 311 # Use this when hash items are dynamically allocated, to ensure that 312 # you don't have memory leaks. You can pass 'free' or NULL as a free_fn. 313 # Returns the item, or NULL if there is no such item. 314 # 315 # @param key [::FFI::Pointer, #to_ptr] 316 # @param free_fn [::FFI::Pointer, #to_ptr] 317 # @return [::FFI::Pointer] 318 def freefn(key, free_fn) 319 raise DestroyedError unless @ptr 320 self_p = @ptr 321 result = ::CZMQ::FFI.zhashx_freefn(self_p, key, free_fn) 322 result 323 end 324 325 # Return the number of keys/items in the hash table 326 # 327 # @return [Integer] 328 def size() 329 raise DestroyedError unless @ptr 330 self_p = @ptr 331 result = ::CZMQ::FFI.zhashx_size(self_p) 332 result 333 end 334 335 # Return a zlistx_t containing the keys for the items in the 336 # table. Uses the key_duplicator to duplicate all keys and sets the 337 # key_destructor as destructor for the list. 338 # 339 # @return [Zlistx] 340 def keys() 341 raise DestroyedError unless @ptr 342 self_p = @ptr 343 result = ::CZMQ::FFI.zhashx_keys(self_p) 344 result = Zlistx.__new result, true 345 result 346 end 347 348 # Return a zlistx_t containing the values for the items in the 349 # table. Uses the duplicator to duplicate all items and sets the 350 # destructor as destructor for the list. 351 # 352 # @return [Zlistx] 353 def values() 354 raise DestroyedError unless @ptr 355 self_p = @ptr 356 result = ::CZMQ::FFI.zhashx_values(self_p) 357 result = Zlistx.__new result, true 358 result 359 end 360 361 # Simple iterator; returns first item in hash table, in no given order, 362 # or NULL if the table is empty. This method is simpler to use than the 363 # foreach() method, which is deprecated. To access the key for this item 364 # use zhashx_cursor(). NOTE: do NOT modify the table while iterating. 365 # 366 # @return [::FFI::Pointer] 367 def first() 368 raise DestroyedError unless @ptr 369 self_p = @ptr 370 result = ::CZMQ::FFI.zhashx_first(self_p) 371 result 372 end 373 374 # Simple iterator; returns next item in hash table, in no given order, 375 # or NULL if the last item was already returned. Use this together with 376 # zhashx_first() to process all items in a hash table. If you need the 377 # items in sorted order, use zhashx_keys() and then zlistx_sort(). To 378 # access the key for this item use zhashx_cursor(). NOTE: do NOT modify 379 # the table while iterating. 380 # 381 # @return [::FFI::Pointer] 382 def next() 383 raise DestroyedError unless @ptr 384 self_p = @ptr 385 result = ::CZMQ::FFI.zhashx_next(self_p) 386 result 387 end 388 389 # After a successful first/next method, returns the key for the item that 390 # was returned. This is a constant string that you may not modify or 391 # deallocate, and which lasts as long as the item in the hash. After an 392 # unsuccessful first/next, returns NULL. 393 # 394 # @return [::FFI::Pointer] 395 def cursor() 396 raise DestroyedError unless @ptr 397 self_p = @ptr 398 result = ::CZMQ::FFI.zhashx_cursor(self_p) 399 result 400 end 401 402 # Add a comment to hash table before saving to disk. You can add as many 403 # comment lines as you like. These comment lines are discarded when loading 404 # the file. If you use a null format, all comments are deleted. 405 # 406 # @param format [String, #to_s, nil] 407 # @param args [Array<Object>] see https://github.com/ffi/ffi/wiki/examples#using-varargs 408 # @return [void] 409 def comment(format, *args) 410 raise DestroyedError unless @ptr 411 self_p = @ptr 412 result = ::CZMQ::FFI.zhashx_comment(self_p, format, *args) 413 result 414 end 415 416 # Save hash table to a text file in name=value format. Hash values must be 417 # printable strings; keys may not contain '=' character. Returns 0 if OK, 418 # else -1 if a file error occurred. 419 # 420 # @param filename [String, #to_s, nil] 421 # @return [Integer] 422 def save(filename) 423 raise DestroyedError unless @ptr 424 self_p = @ptr 425 result = ::CZMQ::FFI.zhashx_save(self_p, filename) 426 result 427 end 428 429 # Load hash table from a text file in name=value format; hash table must 430 # already exist. Hash values must printable strings; keys may not contain 431 # '=' character. Returns 0 if OK, else -1 if a file was not readable. 432 # 433 # @param filename [String, #to_s, nil] 434 # @return [Integer] 435 def load(filename) 436 raise DestroyedError unless @ptr 437 self_p = @ptr 438 result = ::CZMQ::FFI.zhashx_load(self_p, filename) 439 result 440 end 441 442 # When a hash table was loaded from a file by zhashx_load, this method will 443 # reload the file if it has been modified since, and is "stable", i.e. not 444 # still changing. Returns 0 if OK, -1 if there was an error reloading the 445 # file. 446 # 447 # @return [Integer] 448 def refresh() 449 raise DestroyedError unless @ptr 450 self_p = @ptr 451 result = ::CZMQ::FFI.zhashx_refresh(self_p) 452 result 453 end 454 455 # Serialize hash table to a binary frame that can be sent in a message. 456 # The packed format is compatible with the 'dictionary' type defined in 457 # http://rfc.zeromq.org/spec:35/FILEMQ, and implemented by zproto: 458 # 459 # ; A list of name/value pairs 460 # dictionary = dict-count *( dict-name dict-value ) 461 # dict-count = number-4 462 # dict-value = longstr 463 # dict-name = string 464 # 465 # ; Strings are always length + text contents 466 # longstr = number-4 *VCHAR 467 # string = number-1 *VCHAR 468 # 469 # ; Numbers are unsigned integers in network byte order 470 # number-1 = 1OCTET 471 # number-4 = 4OCTET 472 # 473 # Comments are not included in the packed data. Item values MUST be 474 # strings. 475 # 476 # @return [Zframe] 477 def pack() 478 raise DestroyedError unless @ptr 479 self_p = @ptr 480 result = ::CZMQ::FFI.zhashx_pack(self_p) 481 result = Zframe.__new result, true 482 result 483 end 484 485 # Same as pack but uses a user-defined serializer function to convert items 486 # into longstr. 487 # 488 # @param serializer [::FFI::Pointer, #to_ptr] 489 # @return [Zframe] 490 def pack_own(serializer) 491 raise DestroyedError unless @ptr 492 self_p = @ptr 493 result = ::CZMQ::FFI.zhashx_pack_own(self_p, serializer) 494 result = Zframe.__new result, true 495 result 496 end 497 498 # Make a copy of the list; items are duplicated if you set a duplicator 499 # for the list, otherwise not. Copying a null reference returns a null 500 # reference. Note that this method's behavior changed slightly for CZMQ 501 # v3.x, as it does not set nor respect autofree. It does however let you 502 # duplicate any hash table safely. The old behavior is in zhashx_dup_v2. 503 # 504 # @return [Zhashx] 505 def dup() 506 raise DestroyedError unless @ptr 507 self_p = @ptr 508 result = ::CZMQ::FFI.zhashx_dup(self_p) 509 result = Zhashx.__new result, true 510 result 511 end 512 513 # Set a user-defined deallocator for hash items; by default items are not 514 # freed when the hash is destroyed. 515 # 516 # @param destructor [::FFI::Pointer, #to_ptr] 517 # @return [void] 518 def set_destructor(destructor) 519 raise DestroyedError unless @ptr 520 self_p = @ptr 521 result = ::CZMQ::FFI.zhashx_set_destructor(self_p, destructor) 522 result 523 end 524 525 # Set a user-defined duplicator for hash items; by default items are not 526 # copied when the hash is duplicated. 527 # 528 # @param duplicator [::FFI::Pointer, #to_ptr] 529 # @return [void] 530 def set_duplicator(duplicator) 531 raise DestroyedError unless @ptr 532 self_p = @ptr 533 result = ::CZMQ::FFI.zhashx_set_duplicator(self_p, duplicator) 534 result 535 end 536 537 # Set a user-defined deallocator for keys; by default keys are freed 538 # when the hash is destroyed using free(). 539 # 540 # @param destructor [::FFI::Pointer, #to_ptr] 541 # @return [void] 542 def set_key_destructor(destructor) 543 raise DestroyedError unless @ptr 544 self_p = @ptr 545 result = ::CZMQ::FFI.zhashx_set_key_destructor(self_p, destructor) 546 result 547 end 548 549 # Set a user-defined duplicator for keys; by default keys are duplicated 550 # using strdup. 551 # 552 # @param duplicator [::FFI::Pointer, #to_ptr] 553 # @return [void] 554 def set_key_duplicator(duplicator) 555 raise DestroyedError unless @ptr 556 self_p = @ptr 557 result = ::CZMQ::FFI.zhashx_set_key_duplicator(self_p, duplicator) 558 result 559 end 560 561 # Set a user-defined comparator for keys; by default keys are 562 # compared using strcmp. 563 # The callback function should return zero (0) on matching 564 # items. 565 # 566 # @param comparator [::FFI::Pointer, #to_ptr] 567 # @return [void] 568 def set_key_comparator(comparator) 569 raise DestroyedError unless @ptr 570 self_p = @ptr 571 result = ::CZMQ::FFI.zhashx_set_key_comparator(self_p, comparator) 572 result 573 end 574 575 # Set a user-defined hash function for keys; by default keys are 576 # hashed by a modified Bernstein hashing function. 577 # 578 # @param hasher [::FFI::Pointer, #to_ptr] 579 # @return [void] 580 def set_key_hasher(hasher) 581 raise DestroyedError unless @ptr 582 self_p = @ptr 583 result = ::CZMQ::FFI.zhashx_set_key_hasher(self_p, hasher) 584 result 585 end 586 587 # Make copy of hash table; if supplied table is null, returns null. 588 # Does not copy items themselves. Rebuilds new table so may be slow on 589 # very large tables. NOTE: only works with item values that are strings 590 # since there's no other way to know how to duplicate the item value. 591 # 592 # @return [Zhashx] 593 def dup_v2() 594 raise DestroyedError unless @ptr 595 self_p = @ptr 596 result = ::CZMQ::FFI.zhashx_dup_v2(self_p) 597 result = Zhashx.__new result, false 598 result 599 end 600 601 # Self test of this class. 602 # 603 # @param verbose [Boolean] 604 # @return [void] 605 def self.test(verbose) 606 verbose = !(0==verbose||!verbose) # boolean 607 result = ::CZMQ::FFI.zhashx_test(verbose) 608 result 609 end 610 end 611 end 612end 613 614################################################################################ 615# THIS FILE IS 100% GENERATED BY ZPROJECT; DO NOT EDIT EXCEPT EXPERIMENTALLY # 616# Read the zproject/README.md for information about making permanent changes. # 617################################################################################ 618