Class: CZMQ::FFI::Zlist

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

Overview

Note:

This class is 100% generated using zproject.

simple generic list container

Defined Under Namespace

Classes: DestroyedError

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ptr, finalize = true) ⇒ Zlist

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/zlist.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/zlist.rb', line 18

alias :__new :new

.compare_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: Comparison function e.g. for sorting and removing.

typedef int (zlist_compare_fn) (
    void *item1, void *item2);



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

def self.compare_fn
  ::FFI::Function.new :int, [:pointer, :pointer], blocking: true do |item1, item2|
    result = yield item1, item2
    result = Integer(result)
    result
  end
end

.create_finalizer_for(ptr) ⇒ Proc

Parameters:

  • ptr (::FFI::Pointer)

Returns:

  • (Proc) 


35
36
37
38
39
40
41
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.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.zlist_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 zlist_freefn method

typedef void (zlist_free_fn) (
    void *data);



102
103
104
105
106
107
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 102

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

.new ⇒ CZMQ::Zlist

Create a new list container

Returns:

  • (CZMQ::Zlist) 


111
112
113
114
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 111

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

.test(verbose) ⇒ void

This method returns an undefined value.

Self test of this class.

Parameters:

  • verbose (Boolean) 


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

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

Instance Method Details

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

Return internal pointer

Returns:

  • (::FFI::Pointer)

Raises:



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

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:



59
60
61
62
63
64
65
66
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.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 ⇒ 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.



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

def __undef_finalizer
  ObjectSpace.undefine_finalizer self
  @finalizer = nil
end

#append(item) ⇒ Integer

Append an item to the end of the list, return 0 if OK or -1 if this failed for some reason (out of memory). Note that if a duplicator has been set, this method will also duplicate the item.

Parameters:

  • item (::FFI::Pointer, #to_ptr)

Returns:

  • (Integer)

Raises:



196
197
198
199
200
201
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 196

def append(item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zlist_append(self_p, item)
  result
end

#autofree ⇒ void

This method returns an undefined value.

Set list for automatic item destruction; item values MUST be strings. By default a list item refers to a value held elsewhere. When you set this, each time you append or push a list item, zlist will take a copy of the string value. Then, when you destroy the list, it will free all item values automatically. If you use any other technique to allocate list values, you must free them explicitly before destroying the list. The usual technique is to pop list items and destroy them, until the list is empty.

Raises:



309
310
311
312
313
314
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 309

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

#comparefn(fn) ⇒ void

This method returns an undefined value.

Sets a compare function for this list. The function compares two items. It returns an integer less than, equal to, or greater than zero if the first item is found, respectively, to be less than, to match, or be greater than the second item. This function is used for sorting, removal and exists checking.

Parameters:

  • fn (::FFI::Pointer, #to_ptr)

Raises:



324
325
326
327
328
329
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 324

def comparefn(fn)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zlist_comparefn(self_p, fn)
  result
end

#destroy ⇒ void

This method returns an undefined value.

Destroy a list container



119
120
121
122
123
124
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 119

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

#dup ⇒ Zlist

Make a copy of list. If the list has autofree set, the copied list will duplicate all items, which must be strings. Otherwise, the list will hold pointers back to the items in the original list. If list is null, returns NULL.

Returns:

Raises:



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

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

#exists(item) ⇒ Boolean

Checks if an item already is present. Uses compare method to determine if items are equal. If the compare method is NULL the check will only compare pointers. Returns true if item is present else false.

Parameters:

  • item (::FFI::Pointer, #to_ptr)

Returns:

  • (Boolean)

Raises:



232
233
234
235
236
237
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 232

def exists(item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zlist_exists(self_p, item)
  result
end

#first ⇒ ::FFI::Pointer

Return the item at the head of list. If the list is empty, returns NULL. Leaves cursor pointing at the head item, or NULL if the list is empty.

Returns:

  • (::FFI::Pointer)

Raises:



130
131
132
133
134
135
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 130

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

#freefn(item, fn, at_tail) ⇒ ::FFI::Pointer

Set a free function for the specified list item. When the item is destroyed, the free function, if any, is called on that item. Use this when list 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:

  • item (::FFI::Pointer, #to_ptr)
  • fn (::FFI::Pointer, #to_ptr)
  • at_tail (Boolean)

Returns:

  • (::FFI::Pointer)

Raises:



341
342
343
344
345
346
347
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 341

def freefn(item, fn, at_tail)
  raise DestroyedError unless @ptr
  self_p = @ptr
  at_tail = !(0==at_tail||!at_tail) # boolean
  result = ::CZMQ::FFI.zlist_freefn(self_p, item, fn, at_tail)
  result
end

#head ⇒ ::FFI::Pointer

Return first item in the list, or null, leaves the cursor

Returns:

  • (::FFI::Pointer)

Raises:



162
163
164
165
166
167
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 162

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

#item ⇒ ::FFI::Pointer

Return the current item of list. If the list is empty, returns NULL. Leaves cursor pointing at the current item, or NULL if the list is empty.

Returns:

  • (::FFI::Pointer)

Raises:



183
184
185
186
187
188
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 183

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

#last ⇒ ::FFI::Pointer

Return the item at the tail of list. If the list is empty, returns NULL. Leaves cursor pointing at the tail item, or NULL if the list is empty.

Returns:

  • (::FFI::Pointer)

Raises:



152
153
154
155
156
157
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 152

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

#next ⇒ ::FFI::Pointer

Return the next item. If the list is empty, returns NULL. To move to the start of the list call zlist_first (). Advances the cursor.

Returns:

  • (::FFI::Pointer)

Raises:



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

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

#null? ⇒ Boolean

Returns:

  • (Boolean) 


43
44
45
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 43

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

#pop ⇒ ::FFI::Pointer

Pop the item off the start of the list, if any

Returns:

  • (::FFI::Pointer)

Raises:



219
220
221
222
223
224
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 219

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

#purge ⇒ void

This method returns an undefined value.

Purge all items from list

Raises:



267
268
269
270
271
272
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 267

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

#push(item) ⇒ Integer

Push an item to the start of the list, return 0 if OK or -1 if this failed for some reason (out of memory). Note that if a duplicator has been set, this method will also duplicate the item.

Parameters:

  • item (::FFI::Pointer, #to_ptr)

Returns:

  • (Integer)

Raises:



209
210
211
212
213
214
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 209

def push(item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zlist_push(self_p, item)
  result
end

#remove(item) ⇒ void

This method returns an undefined value.

Remove the specified item from the list if present

Parameters:

  • item (::FFI::Pointer, #to_ptr)

Raises:



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

def remove(item)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zlist_remove(self_p, item)
  result
end

#size ⇒ Integer

Return number of items in the list

Returns:

  • (Integer)

Raises:



277
278
279
280
281
282
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 277

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

#sort(compare) ⇒ void

This method returns an undefined value.

Sort the list. If the compare function is null, sorts the list by ascending key value using a straight ASCII comparison. If you specify a compare function, this decides how items are sorted. The sort is not stable, so may reorder items with the same keys. The algorithm used is combsort, a compromise between performance and simplicity.

Parameters:

  • compare (::FFI::Pointer, #to_ptr)

Raises:



292
293
294
295
296
297
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 292

def sort(compare)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zlist_sort(self_p, compare)
  result
end

#tail ⇒ ::FFI::Pointer

Return last item in the list, or null, leaves the cursor

Returns:

  • (::FFI::Pointer)

Raises:



172
173
174
175
176
177
 
# File 'lib/czmq-ffi-gen/czmq/ffi/zlist.rb', line 172

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