Class: Fiddle::Pointer

Inherits:
Object
  • Object
show all
Defined in:
ext/fiddle/pointer.c,
ext/fiddle/pointer.c

Overview

Fiddle::Pointer is a class to handle C pointers

Direct Known Subclasses

CStructEntity

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#Fiddle::Pointer.new(address) ⇒ Object #new(address, size) ⇒ Object #new(address, size, freefunc) ⇒ Object

Create a new pointer to address with an optional size and freefunc.

freefunc will be called when the instance is garbage collected.



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'ext/fiddle/pointer.c', line 166

static VALUE
rb_fiddle_ptr_initialize(int argc, VALUE argv[], VALUE self)
{
    VALUE ptr, sym, size, wrap = 0, funcwrap = 0;
    struct ptr_data *data;
    void *p = NULL;
    freefunc_t f = NULL;
    long s = 0;

    if (rb_scan_args(argc, argv, "12", &ptr, &size, &sym) >= 1) {
  VALUE addrnum = rb_Integer(ptr);
  if (addrnum != ptr) wrap = ptr;
  p = NUM2PTR(addrnum);
    }
    if (argc >= 2) {
  s = NUM2LONG(size);
    }
    if (argc >= 3) {
  f = get_freefunc(sym, &funcwrap);
    }

    if (p) {
  TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
  if (data->ptr && data->free) {
      /* Free previous memory. Use of inappropriate initialize may cause SEGV. */
      (*(data->free))(data->ptr);
  }
  data->wrap[0] = wrap;
  data->wrap[1] = funcwrap;
  data->ptr  = p;
  data->size = s;
  data->free = f;
    }

    return Qnil;
}

Class Method Details

.Fiddle::Pointer ⇒ Object .to_ptr(val) ⇒ Object

Get the underlying pointer for ruby object val and return it as a Fiddle::Pointer object.



722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
 
# File 'ext/fiddle/pointer.c', line 722

static VALUE
rb_fiddle_ptr_s_to_ptr(VALUE self, VALUE val)
{
    VALUE ptr, wrap = val, vptr;

    if (RTEST(rb_obj_is_kind_of(val, rb_cIO))){
  rb_io_t *fptr;
  FILE *fp;
  GetOpenFile(val, fptr);
  fp = rb_io_stdio_file(fptr);
  ptr = rb_fiddle_ptr_new(fp, 0, NULL);
    }
    else if (RTEST(rb_obj_is_kind_of(val, rb_cString))){
  char *str = StringValuePtr(val);
  ptr = rb_fiddle_ptr_new(str, RSTRING_LEN(val), NULL);
    }
    else if ((vptr = rb_check_funcall(val, id_to_ptr, 0, 0)) != Qundef){
  if (rb_obj_is_kind_of(vptr, rb_cPointer)){
      ptr = vptr;
      wrap = 0;
  }
  else{
      rb_raise(rb_eFiddleDLError, "to_ptr should return a Fiddle::Pointer object");
  }
    }
    else{
  VALUE num = rb_Integer(val);
  if (num == val) wrap = 0;
  ptr = rb_fiddle_ptr_new(NUM2PTR(num), 0, NULL);
    }
    if (wrap) RPTR_DATA(ptr)->wrap[0] = wrap;
    return ptr;
}

.Fiddle::Pointer.malloc(size, freefunc = nil) ⇒ Object .Fiddle::Pointer.malloc(size, freefunc) {|pointer| ... } ⇒ Object

Examples

# Automatically freeing the pointer when the block is exited - recommended
Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE) do |pointer|
  ...
end

# Manually freeing but relying on the garbage collector otherwise
pointer = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
...
pointer.call_free

# Relying on the garbage collector - may lead to unlimited memory allocated before freeing any, but safe
pointer = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
...

# Only manually freeing
pointer = Fiddle::Pointer.malloc(size)
begin
  ...
ensure
  Fiddle.free pointer
end

# No free function and no call to free - the native memory will leak if the pointer is garbage collected
pointer = Fiddle::Pointer.malloc(size)
...

Allocate size bytes of memory and associate it with an optional freefunc.

If a block is supplied, the pointer will be yielded to the block instead of being returned, and the return value of the block will be returned. A freefunc must be supplied if a block is.

If a freefunc is supplied it will be called once, when the pointer is garbage collected or when the block is left if a block is supplied or when the user calls call_free, whichever happens first. freefunc must be an address pointing to a function or an instance of Fiddle::Function.

Overloads:

  • .Fiddle::Pointer.malloc(size, freefunc) {|pointer| ... } ⇒ Object

    Yields:

    • (pointer) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'ext/fiddle/pointer.c', line 251

static VALUE
rb_fiddle_ptr_s_malloc(int argc, VALUE argv[], VALUE klass)
{
    VALUE size, sym, obj, wrap = 0;
    long s;
    freefunc_t f;

    switch (rb_scan_args(argc, argv, "11", &size, &sym)) {
      case 1:
  s = NUM2LONG(size);
  f = NULL;
  break;
      case 2:
  s = NUM2LONG(size);
  f = get_freefunc(sym, &wrap);
  break;
      default:
  rb_bug("rb_fiddle_ptr_s_malloc");
    }

    obj = rb_fiddle_ptr_malloc(klass, s,f);
    if (wrap) RPTR_DATA(obj)->wrap[1] = wrap;

    if (rb_block_given_p()) {
        if (!f) {
            rb_raise(rb_eArgError, "a free function must be supplied to Fiddle::Pointer.malloc when it is called with a block");
        }
        return rb_ensure(rb_yield, obj, rb_fiddle_ptr_call_free, obj);
    } else {
        return obj;
    }
}

.Fiddle::Pointer ⇒ Object .to_ptr(val) ⇒ Object

Get the underlying pointer for ruby object val and return it as a Fiddle::Pointer object.



722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
 
# File 'ext/fiddle/pointer.c', line 722

static VALUE
rb_fiddle_ptr_s_to_ptr(VALUE self, VALUE val)
{
    VALUE ptr, wrap = val, vptr;

    if (RTEST(rb_obj_is_kind_of(val, rb_cIO))){
  rb_io_t *fptr;
  FILE *fp;
  GetOpenFile(val, fptr);
  fp = rb_io_stdio_file(fptr);
  ptr = rb_fiddle_ptr_new(fp, 0, NULL);
    }
    else if (RTEST(rb_obj_is_kind_of(val, rb_cString))){
  char *str = StringValuePtr(val);
  ptr = rb_fiddle_ptr_new(str, RSTRING_LEN(val), NULL);
    }
    else if ((vptr = rb_check_funcall(val, id_to_ptr, 0, 0)) != Qundef){
  if (rb_obj_is_kind_of(vptr, rb_cPointer)){
      ptr = vptr;
      wrap = 0;
  }
  else{
      rb_raise(rb_eFiddleDLError, "to_ptr should return a Fiddle::Pointer object");
  }
    }
    else{
  VALUE num = rb_Integer(val);
  if (num == val) wrap = 0;
  ptr = rb_fiddle_ptr_new(NUM2PTR(num), 0, NULL);
    }
    if (wrap) RPTR_DATA(ptr)->wrap[0] = wrap;
    return ptr;
}

Instance Method Details

#+(n) ⇒ Object

Returns a new pointer instance that has been advanced n bytes.



576
577
578
579
580
581
582
583
584
585
586
 
# File 'ext/fiddle/pointer.c', line 576

static VALUE
rb_fiddle_ptr_plus(VALUE self, VALUE other)
{
    void *ptr;
    long num, size;

    ptr = rb_fiddle_ptr2cptr(self);
    size = RPTR_DATA(self)->size;
    num = NUM2LONG(other);
    return rb_fiddle_ptr_new((char *)ptr + num, size - num, 0);
}

#ptr ⇒ Object

Returns a new Fiddle::Pointer instance that is a dereferenced pointer for this pointer.

Analogous to the star operator in C.



319
320
321
322
323
324
325
326
 
# File 'ext/fiddle/pointer.c', line 319

static VALUE
rb_fiddle_ptr_ptr(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return rb_fiddle_ptr_new(*((void**)(data->ptr)),0,0);
}

#-(n) ⇒ Object

Returns a new pointer instance that has been moved back n bytes.



594
595
596
597
598
599
600
601
602
603
604
 
# File 'ext/fiddle/pointer.c', line 594

static VALUE
rb_fiddle_ptr_minus(VALUE self, VALUE other)
{
    void *ptr;
    long num, size;

    ptr = rb_fiddle_ptr2cptr(self);
    size = RPTR_DATA(self)->size;
    num = NUM2LONG(other);
    return rb_fiddle_ptr_new((char *)ptr - num, size + num, 0);
}

#ref ⇒ Object

Returns a new Fiddle::Pointer instance that is a reference pointer for this pointer.

Analogous to the ampersand operator in C.



336
337
338
339
340
341
342
343
 
# File 'ext/fiddle/pointer.c', line 336

static VALUE
rb_fiddle_ptr_ref(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return rb_fiddle_ptr_new(&(data->ptr),0,0);
}

#<=>(other) ⇒ -1, ...

Returns -1 if less than, 0 if equal to, 1 if greater than other.

Returns nil if ptr cannot be compared to other.

Returns:

  • (-1, 0, 1, nil) 


555
556
557
558
559
560
561
562
563
564
565
566
567
568
 
# File 'ext/fiddle/pointer.c', line 555

static VALUE
rb_fiddle_ptr_cmp(VALUE self, VALUE other)
{
    void *ptr1, *ptr2;
    SIGNED_VALUE diff;

    if(!rb_obj_is_kind_of(other, rb_cPointer)) return Qnil;

    ptr1 = rb_fiddle_ptr2cptr(self);
    ptr2 = rb_fiddle_ptr2cptr(other);
    diff = (SIGNED_VALUE)ptr1 - (SIGNED_VALUE)ptr2;
    if (!diff) return INT2FIX(0);
    return diff > 0 ? INT2NUM(1) : INT2NUM(-1);
}

#==(other) ⇒ Boolean #eql?(other) ⇒ Boolean

Returns true if other wraps the same pointer, otherwise returns false.

Overloads:

  • #==(other) ⇒ Boolean

    Returns:

    • (Boolean)
  • #eql?(other) ⇒ Boolean

    Returns:

    • (Boolean) 


534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'ext/fiddle/pointer.c', line 534

static VALUE
rb_fiddle_ptr_eql(VALUE self, VALUE other)
{
    void *ptr1, *ptr2;

    if(!rb_obj_is_kind_of(other, rb_cPointer)) return Qfalse;

    ptr1 = rb_fiddle_ptr2cptr(self);
    ptr2 = rb_fiddle_ptr2cptr(other);

    return ptr1 == ptr2 ? Qtrue : Qfalse;
}

#[](index) ⇒ Integer #[](start, length) ⇒ String

Returns integer stored at index.

If start and length are given, a string containing the bytes from start of length will be returned.

Overloads:

  • #[](index) ⇒ Integer

    Returns:

    • (Integer)
  • #[](start, length) ⇒ String

    Returns:

    • (String) 


616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
 
# File 'ext/fiddle/pointer.c', line 616

static VALUE
rb_fiddle_ptr_aref(int argc, VALUE argv[], VALUE self)
{
    VALUE arg0, arg1;
    VALUE retval = Qnil;
    size_t offset, len;
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    if (!data->ptr) rb_raise(rb_eFiddleDLError, "NULL pointer dereference");
    switch( rb_scan_args(argc, argv, "11", &arg0, &arg1) ){
      case 1:
  offset = NUM2ULONG(arg0);
  retval = INT2NUM(*((char *)data->ptr + offset));
  break;
      case 2:
  offset = NUM2ULONG(arg0);
  len    = NUM2ULONG(arg1);
  retval = rb_str_new((char *)data->ptr + offset, len);
  break;
      default:
  rb_bug("rb_fiddle_ptr_aref()");
    }
    return retval;
}

#[]=(index) ⇒ Integer #[]=(start, length) ⇒ String

Set the value at index to int.

Or, set the memory at start until length with the contents of string, the memory from dl_cptr, or the memory pointed at by the memory address addr.

Overloads:

  • #[]=(index) ⇒ Integer

    Returns:

    • (Integer)
  • #[]=(start, length) ⇒ String

    Returns:

    • (String) 


653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
 
# File 'ext/fiddle/pointer.c', line 653

static VALUE
rb_fiddle_ptr_aset(int argc, VALUE argv[], VALUE self)
{
    VALUE arg0, arg1, arg2;
    VALUE retval = Qnil;
    size_t offset, len;
    void *mem;
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    if (!data->ptr) rb_raise(rb_eFiddleDLError, "NULL pointer dereference");
    switch( rb_scan_args(argc, argv, "21", &arg0, &arg1, &arg2) ){
      case 2:
  offset = NUM2ULONG(arg0);
  ((char*)data->ptr)[offset] = NUM2UINT(arg1);
  retval = arg1;
  break;
      case 3:
  offset = NUM2ULONG(arg0);
  len    = NUM2ULONG(arg1);
  if (RB_TYPE_P(arg2, T_STRING)) {
      mem = StringValuePtr(arg2);
  }
  else if( rb_obj_is_kind_of(arg2, rb_cPointer) ){
      mem = rb_fiddle_ptr2cptr(arg2);
  }
  else{
      mem    = NUM2PTR(arg2);
  }
  memcpy((char *)data->ptr + offset, mem, len);
  retval = arg2;
  break;
      default:
  rb_bug("rb_fiddle_ptr_aset()");
    }
    return retval;
}

#call_free ⇒ nil

Call the free function for this pointer. Calling more than once will do nothing. Does nothing if there is no free function attached.

Returns:

  • (nil) 


412
413
414
415
416
417
418
419
 
# File 'ext/fiddle/pointer.c', line 412

static VALUE
rb_fiddle_ptr_call_free(VALUE self)
{
    struct ptr_data *pdata;
    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, pdata);
    fiddle_ptr_free_ptr(pdata);
    return Qnil;
}

#==(other) ⇒ Boolean #eql?(other) ⇒ Boolean

Returns true if other wraps the same pointer, otherwise returns false.

Overloads:

  • #==(other) ⇒ Boolean

    Returns:

    • (Boolean)
  • #eql?(other) ⇒ Boolean

    Returns:

    • (Boolean) 


534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'ext/fiddle/pointer.c', line 534

static VALUE
rb_fiddle_ptr_eql(VALUE self, VALUE other)
{
    void *ptr1, *ptr2;

    if(!rb_obj_is_kind_of(other, rb_cPointer)) return Qfalse;

    ptr1 = rb_fiddle_ptr2cptr(self);
    ptr2 = rb_fiddle_ptr2cptr(other);

    return ptr1 == ptr2 ? Qtrue : Qfalse;
}

#free ⇒ Fiddle::Function

Get the free function for this pointer.

Returns a new instance of Fiddle::Function.

See Fiddle::Function.new

Returns:



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
 
# File 'ext/fiddle/pointer.c', line 385

static VALUE
rb_fiddle_ptr_free_get(VALUE self)
{
    struct ptr_data *pdata;
    VALUE address;
    VALUE arg_types;
    VALUE ret_type;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, pdata);

    if (!pdata->free)
  return Qnil;

    address = PTR2NUM(pdata->free);
    ret_type = INT2NUM(TYPE_VOID);
    arg_types = rb_ary_new();
    rb_ary_push(arg_types, INT2NUM(TYPE_VOIDP));

    return rb_fiddle_new_function(address, arg_types, ret_type);
}

#free=(function) ⇒ Object

Set the free function for this pointer to function in the given Fiddle::Function.



365
366
367
368
369
370
371
372
373
374
 
# File 'ext/fiddle/pointer.c', line 365

static VALUE
rb_fiddle_ptr_free_set(VALUE self, VALUE val)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    data->free = get_freefunc(val, &data->wrap[1]);

    return Qnil;
}

#freed? ⇒ Boolean

Returns if the free function for this pointer has been called.

Returns:

  • (Boolean) 


426
427
428
429
430
431
432
 
# File 'ext/fiddle/pointer.c', line 426

static VALUE
rb_fiddle_ptr_freed_p(VALUE self)
{
    struct ptr_data *pdata;
    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, pdata);
    return pdata->freed ? Qtrue : Qfalse;
}

#inspect ⇒ Object

Returns a string formatted with an easily readable representation of the internal state of the pointer.



516
517
518
519
520
521
522
523
524
 
# File 'ext/fiddle/pointer.c', line 516

static VALUE
rb_fiddle_ptr_inspect(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return rb_sprintf("#<%"PRIsVALUE":%p ptr=%p size=%ld free=%p>",
          RB_OBJ_CLASSNAME(self), (void *)data, data->ptr, data->size, (void *)data->free);
}

#null? ⇒ Boolean

Returns true if this is a null pointer.

Returns:

  • (Boolean) 


350
351
352
353
354
355
356
357
 
# File 'ext/fiddle/pointer.c', line 350

static VALUE
rb_fiddle_ptr_null_p(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return data->ptr ? Qfalse : Qtrue;
}

#ptr ⇒ Object

Returns a new Fiddle::Pointer instance that is a dereferenced pointer for this pointer.

Analogous to the star operator in C.



319
320
321
322
323
324
325
326
 
# File 'ext/fiddle/pointer.c', line 319

static VALUE
rb_fiddle_ptr_ptr(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return rb_fiddle_ptr_new(*((void**)(data->ptr)),0,0);
}

#ref ⇒ Object

Returns a new Fiddle::Pointer instance that is a reference pointer for this pointer.

Analogous to the ampersand operator in C.



336
337
338
339
340
341
342
343
 
# File 'ext/fiddle/pointer.c', line 336

static VALUE
rb_fiddle_ptr_ref(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return rb_fiddle_ptr_new(&(data->ptr),0,0);
}

#size ⇒ Object

Get the size of this pointer.



708
709
710
711
712
 
# File 'ext/fiddle/pointer.c', line 708

static VALUE
rb_fiddle_ptr_size_get(VALUE self)
{
    return LONG2NUM(RPTR_DATA(self)->size);
}

#size=(size) ⇒ Object

Set the size of this pointer to size



696
697
698
699
700
701
 
# File 'ext/fiddle/pointer.c', line 696

static VALUE
rb_fiddle_ptr_size_set(VALUE self, VALUE size)
{
    RPTR_DATA(self)->size = NUM2LONG(size);
    return size;
}

#to_i ⇒ Object

Returns the integer memory location of this pointer.



289
290
291
292
293
294
295
296
 
# File 'ext/fiddle/pointer.c', line 289

static VALUE
rb_fiddle_ptr_to_i(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return PTR2NUM(data->ptr);
}

#to_i ⇒ Object

Returns the integer memory location of this pointer.



289
290
291
292
293
294
295
296
 
# File 'ext/fiddle/pointer.c', line 289

static VALUE
rb_fiddle_ptr_to_i(VALUE self)
{
    struct ptr_data *data;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return PTR2NUM(data->ptr);
}

#to_s ⇒ String #to_s(len) ⇒ String

Returns the pointer contents as a string.

When called with no arguments, this method will return the contents until the first NULL byte.

When called with len, a string of len bytes will be returned.

See to_str

Overloads:

  • #to_s ⇒ String

    Returns:

    • (String)
  • #to_s(len) ⇒ String

    Returns:

    • (String) 


449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
 
# File 'ext/fiddle/pointer.c', line 449

static VALUE
rb_fiddle_ptr_to_s(int argc, VALUE argv[], VALUE self)
{
    struct ptr_data *data;
    VALUE arg1, val;
    int len;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    switch (rb_scan_args(argc, argv, "01", &arg1)) {
      case 0:
  val = rb_str_new2((char*)(data->ptr));
  break;
      case 1:
  len = NUM2INT(arg1);
  val = rb_str_new((char*)(data->ptr), len);
  break;
      default:
  rb_bug("rb_fiddle_ptr_to_s");
    }

    return val;
}

#to_str ⇒ String #to_str(len) ⇒ String

Returns the pointer contents as a string.

When called with no arguments, this method will return the contents with the length of this pointer’s size.

When called with len, a string of len bytes will be returned.

See to_s

Overloads:

  • #to_str ⇒ String

    Returns:

    • (String)
  • #to_str(len) ⇒ String

    Returns:

    • (String) 


487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
 
# File 'ext/fiddle/pointer.c', line 487

static VALUE
rb_fiddle_ptr_to_str(int argc, VALUE argv[], VALUE self)
{
    struct ptr_data *data;
    VALUE arg1, val;
    int len;

    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    switch (rb_scan_args(argc, argv, "01", &arg1)) {
      case 0:
  val = rb_str_new((char*)(data->ptr),data->size);
  break;
      case 1:
  len = NUM2INT(arg1);
  val = rb_str_new((char*)(data->ptr), len);
  break;
      default:
  rb_bug("rb_fiddle_ptr_to_str");
    }

    return val;
}

#to_value ⇒ Object

Cast this pointer to a ruby object.



303
304
305
306
307
308
309
 
# File 'ext/fiddle/pointer.c', line 303

static VALUE
rb_fiddle_ptr_to_value(VALUE self)
{
    struct ptr_data *data;
    TypedData_Get_Struct(self, struct ptr_data, &fiddle_ptr_data_type, data);
    return (VALUE)(data->ptr);
}