class CZMQ::FFI::Zlist

simple generic list container @note This class is 100% generated using zproject.

Public Class Methods

__new()
Alias for: new
compare_fn() { |item1, item2| ... } click to toggle source

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);

@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/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) click to toggle source

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

# 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() { |data| ... } click to toggle source

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

typedef void (zlist_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/zlist.rb, line 102
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/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
new() click to toggle source

Create a new list container @return [CZMQ::Zlist]

# File lib/czmq-ffi-gen/czmq/ffi/zlist.rb, line 111
def self.new()
  ptr = ::CZMQ::FFI.zlist_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/zlist.rb, line 353
def self.test(verbose)
  verbose = !(0==verbose||!verbose) # boolean
  result = ::CZMQ::FFI.zlist_test(verbose)
  result
end

Public Instance Methods

__ptr() click to toggle source

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

# File lib/czmq-ffi-gen/czmq/ffi/zlist.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/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() 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/zlist.rb, line 71
def __undef_finalizer
  ObjectSpace.undefine_finalizer self
  @finalizer = nil
end
append(item) click to toggle source

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.

@param item [::FFI::Pointer, to_ptr] @return [Integer]

# 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() click to toggle source

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.

@return [void]

# 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) click to toggle source

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.

@param fn [::FFI::Pointer, to_ptr] @return [void]

# 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() click to toggle source

Destroy a list container

@return [void]

# 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() click to toggle source

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.

@return [Zlist]

# 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) click to toggle source

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.

@param item [::FFI::Pointer, to_ptr] @return [Boolean]

# 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() click to toggle source

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.

@return [::FFI::Pointer]

# 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) click to toggle source

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.

@param item [::FFI::Pointer, to_ptr] @param fn [::FFI::Pointer, to_ptr] @param at_tail [Boolean] @return [::FFI::Pointer]

# 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() click to toggle source

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

@return [::FFI::Pointer]

# 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() click to toggle source

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.

@return [::FFI::Pointer]

# 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() click to toggle source

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.

@return [::FFI::Pointer]

# 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() click to toggle source

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.

@return [::FFI::Pointer]

# 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?() click to toggle source

@return [Boolean]

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

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

@return [::FFI::Pointer]

# 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() click to toggle source

Purge all items from list

@return [void]

# 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) click to toggle source

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.

@param item [::FFI::Pointer, to_ptr] @return [Integer]

# 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) click to toggle source

Remove the specified item from the list if present

@param item [::FFI::Pointer, to_ptr] @return [void]

# 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() click to toggle source

Return number of items in the list

@return [Integer]

# 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) click to toggle source

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.

@param compare [::FFI::Pointer, to_ptr] @return [void]

# 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() click to toggle source

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

@return [::FFI::Pointer]

# 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
to_ptr()

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

Alias for: __ptr