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 # simple generic list container 10 # @note This class is 100% generated using zproject. 11 class Zlist 12 # Raised when one tries to use an instance of {Zlist} 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.zlist_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 # Comparison function e.g. for sorting and removing. 78 # typedef int (zlist_compare_fn) ( 79 # void *item1, void *item2); 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.compare_fn 86 ::FFI::Function.new :int, [:pointer, :pointer], blocking: true do |item1, item2| 87 result = yield item1, item2 88 result = Integer(result) 89 result 90 end 91 end 92 93 # Create a new callback of the following type: 94 # Callback function for zlist_freefn method 95 # typedef void (zlist_free_fn) ( 96 # void *data); 97 # 98 # @note WARNING: If your Ruby code doesn't retain a reference to the 99 # FFI::Function object after passing it to a C function call, 100 # it may be garbage collected while C still holds the pointer, 101 # potentially resulting in a segmentation fault. 102 def self.free_fn 103 ::FFI::Function.new :void, [:pointer], blocking: true do |data| 104 result = yield data 105 result 106 end 107 end 108 109 # Create a new list container 110 # @return [CZMQ::Zlist] 111 def self.new() 112 ptr = ::CZMQ::FFI.zlist_new() 113 __new ptr 114 end 115 116 # Destroy a list container 117 # 118 # @return [void] 119 def destroy() 120 return unless @ptr 121 self_p = __ptr_give_ref 122 result = ::CZMQ::FFI.zlist_destroy(self_p) 123 result 124 end 125 126 # Return the item at the head of list. If the list is empty, returns NULL. 127 # Leaves cursor pointing at the head item, or NULL if the list is empty. 128 # 129 # @return [::FFI::Pointer] 130 def first() 131 raise DestroyedError unless @ptr 132 self_p = @ptr 133 result = ::CZMQ::FFI.zlist_first(self_p) 134 result 135 end 136 137 # Return the next item. If the list is empty, returns NULL. To move to 138 # the start of the list call zlist_first (). Advances the cursor. 139 # 140 # @return [::FFI::Pointer] 141 def next() 142 raise DestroyedError unless @ptr 143 self_p = @ptr 144 result = ::CZMQ::FFI.zlist_next(self_p) 145 result 146 end 147 148 # Return the item at the tail of list. If the list is empty, returns NULL. 149 # Leaves cursor pointing at the tail item, or NULL if the list is empty. 150 # 151 # @return [::FFI::Pointer] 152 def last() 153 raise DestroyedError unless @ptr 154 self_p = @ptr 155 result = ::CZMQ::FFI.zlist_last(self_p) 156 result 157 end 158 159 # Return first item in the list, or null, leaves the cursor 160 # 161 # @return [::FFI::Pointer] 162 def head() 163 raise DestroyedError unless @ptr 164 self_p = @ptr 165 result = ::CZMQ::FFI.zlist_head(self_p) 166 result 167 end 168 169 # Return last item in the list, or null, leaves the cursor 170 # 171 # @return [::FFI::Pointer] 172 def tail() 173 raise DestroyedError unless @ptr 174 self_p = @ptr 175 result = ::CZMQ::FFI.zlist_tail(self_p) 176 result 177 end 178 179 # Return the current item of list. If the list is empty, returns NULL. 180 # Leaves cursor pointing at the current item, or NULL if the list is empty. 181 # 182 # @return [::FFI::Pointer] 183 def item() 184 raise DestroyedError unless @ptr 185 self_p = @ptr 186 result = ::CZMQ::FFI.zlist_item(self_p) 187 result 188 end 189 190 # Append an item to the end of the list, return 0 if OK or -1 if this 191 # failed for some reason (out of memory). Note that if a duplicator has 192 # been set, this method will also duplicate the item. 193 # 194 # @param item [::FFI::Pointer, #to_ptr] 195 # @return [Integer] 196 def append(item) 197 raise DestroyedError unless @ptr 198 self_p = @ptr 199 result = ::CZMQ::FFI.zlist_append(self_p, item) 200 result 201 end 202 203 # Push an item to the start of the list, return 0 if OK or -1 if this 204 # failed for some reason (out of memory). Note that if a duplicator has 205 # been set, this method will also duplicate the item. 206 # 207 # @param item [::FFI::Pointer, #to_ptr] 208 # @return [Integer] 209 def push(item) 210 raise DestroyedError unless @ptr 211 self_p = @ptr 212 result = ::CZMQ::FFI.zlist_push(self_p, item) 213 result 214 end 215 216 # Pop the item off the start of the list, if any 217 # 218 # @return [::FFI::Pointer] 219 def pop() 220 raise DestroyedError unless @ptr 221 self_p = @ptr 222 result = ::CZMQ::FFI.zlist_pop(self_p) 223 result 224 end 225 226 # Checks if an item already is present. Uses compare method to determine if 227 # items are equal. If the compare method is NULL the check will only compare 228 # pointers. Returns true if item is present else false. 229 # 230 # @param item [::FFI::Pointer, #to_ptr] 231 # @return [Boolean] 232 def exists(item) 233 raise DestroyedError unless @ptr 234 self_p = @ptr 235 result = ::CZMQ::FFI.zlist_exists(self_p, item) 236 result 237 end 238 239 # Remove the specified item from the list if present 240 # 241 # @param item [::FFI::Pointer, #to_ptr] 242 # @return [void] 243 def remove(item) 244 raise DestroyedError unless @ptr 245 self_p = @ptr 246 result = ::CZMQ::FFI.zlist_remove(self_p, item) 247 result 248 end 249 250 # Make a copy of list. If the list has autofree set, the copied list will 251 # duplicate all items, which must be strings. Otherwise, the list will hold 252 # pointers back to the items in the original list. If list is null, returns 253 # NULL. 254 # 255 # @return [Zlist] 256 def dup() 257 raise DestroyedError unless @ptr 258 self_p = @ptr 259 result = ::CZMQ::FFI.zlist_dup(self_p) 260 result = Zlist.__new result, true 261 result 262 end 263 264 # Purge all items from list 265 # 266 # @return [void] 267 def purge() 268 raise DestroyedError unless @ptr 269 self_p = @ptr 270 result = ::CZMQ::FFI.zlist_purge(self_p) 271 result 272 end 273 274 # Return number of items in the list 275 # 276 # @return [Integer] 277 def size() 278 raise DestroyedError unless @ptr 279 self_p = @ptr 280 result = ::CZMQ::FFI.zlist_size(self_p) 281 result 282 end 283 284 # Sort the list. If the compare function is null, sorts the list by 285 # ascending key value using a straight ASCII comparison. If you specify 286 # a compare function, this decides how items are sorted. The sort is not 287 # stable, so may reorder items with the same keys. The algorithm used is 288 # combsort, a compromise between performance and simplicity. 289 # 290 # @param compare [::FFI::Pointer, #to_ptr] 291 # @return [void] 292 def sort(compare) 293 raise DestroyedError unless @ptr 294 self_p = @ptr 295 result = ::CZMQ::FFI.zlist_sort(self_p, compare) 296 result 297 end 298 299 # Set list for automatic item destruction; item values MUST be strings. 300 # By default a list item refers to a value held elsewhere. When you set 301 # this, each time you append or push a list item, zlist will take a copy 302 # of the string value. Then, when you destroy the list, it will free all 303 # item values automatically. If you use any other technique to allocate 304 # list values, you must free them explicitly before destroying the list. 305 # The usual technique is to pop list items and destroy them, until the 306 # list is empty. 307 # 308 # @return [void] 309 def autofree() 310 raise DestroyedError unless @ptr 311 self_p = @ptr 312 result = ::CZMQ::FFI.zlist_autofree(self_p) 313 result 314 end 315 316 # Sets a compare function for this list. The function compares two items. 317 # It returns an integer less than, equal to, or greater than zero if the 318 # first item is found, respectively, to be less than, to match, or be 319 # greater than the second item. 320 # This function is used for sorting, removal and exists checking. 321 # 322 # @param fn [::FFI::Pointer, #to_ptr] 323 # @return [void] 324 def comparefn(fn) 325 raise DestroyedError unless @ptr 326 self_p = @ptr 327 result = ::CZMQ::FFI.zlist_comparefn(self_p, fn) 328 result 329 end 330 331 # Set a free function for the specified list item. When the item is 332 # destroyed, the free function, if any, is called on that item. 333 # Use this when list items are dynamically allocated, to ensure that 334 # you don't have memory leaks. You can pass 'free' or NULL as a free_fn. 335 # Returns the item, or NULL if there is no such item. 336 # 337 # @param item [::FFI::Pointer, #to_ptr] 338 # @param fn [::FFI::Pointer, #to_ptr] 339 # @param at_tail [Boolean] 340 # @return [::FFI::Pointer] 341 def freefn(item, fn, at_tail) 342 raise DestroyedError unless @ptr 343 self_p = @ptr 344 at_tail = !(0==at_tail||!at_tail) # boolean 345 result = ::CZMQ::FFI.zlist_freefn(self_p, item, fn, at_tail) 346 result 347 end 348 349 # Self test of this class. 350 # 351 # @param verbose [Boolean] 352 # @return [void] 353 def self.test(verbose) 354 verbose = !(0==verbose||!verbose) # boolean 355 result = ::CZMQ::FFI.zlist_test(verbose) 356 result 357 end 358 end 359 end 360end 361 362################################################################################ 363# THIS FILE IS 100% GENERATED BY ZPROJECT; DO NOT EDIT EXCEPT EXPERIMENTALLY # 364# Read the zproject/README.md for information about making permanent changes. # 365################################################################################ 366