From 61962b27a51031965cef70451d369b115868fb11 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Thu, 10 Mar 2011 10:51:38 +0000 Subject: rdoc: 100% documentation coverage! Of course, RDoc doesn't know quantity vs quality :) --- ext/raindrops/linux_tcp_info.c | 51 ++++++++++++++++++++++++++++ ext/raindrops/raindrops.c | 75 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 119 insertions(+), 7 deletions(-) (limited to 'ext') diff --git a/ext/raindrops/linux_tcp_info.c b/ext/raindrops/linux_tcp_info.c index 0c64ded..4aa1c0e 100644 --- a/ext/raindrops/linux_tcp_info.c +++ b/ext/raindrops/linux_tcp_info.c @@ -53,6 +53,14 @@ static VALUE alloc(VALUE klass) return Data_Wrap_Struct(klass, NULL, -1, info); } +/* + * call-seq: + * + * Raindrops::TCP_Info.new(tcp_socket) -> TCP_Info object + * + * Reads a TCP_Info object from any given +tcp_socket+. See the tcp(7) + * manpage and /usr/include/linux/tcp.h for more details. + */ static VALUE init(VALUE self, VALUE io) { int fd = my_fileno(io); @@ -71,6 +79,49 @@ void Init_raindrops_linux_tcp_info(void) VALUE cRaindrops = rb_const_get(rb_cObject, rb_intern("Raindrops")); VALUE cTCP_Info; + /* + * Document-class: Raindrops::TCP_Info + * + * This is used to wrap "struct tcp_info" as described in tcp(7) + * and /usr/include/linux/tcp.h. The following readers methods + * are defined corresponding to the "tcpi_" fields in the + * tcp_info struct. + * + * - state + * - ca_state + * - retransmits + * - probes + * - backoff + * - options + * - snd_wscale + * - rcv_wscale + * - rto + * - ato + * - snd_mss + * - rcv_mss + * - unacked + * - sacked + * - lost + * - retrans + * - fackets + * - last_data_sent + * - last_ack_sent + * - last_data_recv + * - last_ack_recv + * - pmtu + * - rcv_ssthresh + * - rtt + * - rttvar + * - snd_ssthresh + * - snd_cwnd + * - advmss + * - reordering + * - rcv_rtt + * - rcv_space + * - total_retrans + * + * http://kernel.org/doc/man-pages/online/pages/man7/tcp.7.html + */ cTCP_Info = rb_define_class_under(cRaindrops, "TCP_Info", rb_cObject); rb_define_alloc_func(cTCP_Info, alloc); rb_define_private_method(cTCP_Info, "initialize", init, 1); diff --git a/ext/raindrops/raindrops.c b/ext/raindrops/raindrops.c index 766ee02..dbb076a 100644 --- a/ext/raindrops/raindrops.c +++ b/ext/raindrops/raindrops.c @@ -22,7 +22,7 @@ struct raindrop { unsigned long counter; } __attribute__((packed)); -/* allow mmap-ed regions can store more than one raindrop */ +/* allow mmap-ed regions to store more than one raindrop */ struct raindrops { long size; struct raindrop *drops; @@ -59,7 +59,16 @@ static struct raindrops *get(VALUE self) return r; } -/* initializes a Raindrops object to hold +size+ elements */ +/* + * call-seq: + * Raindrops.new(size) -> raindrops object + * + * Initializes a Raindrops object to hold +size+ counters. +size+ is + * only a hint and the actual number of counters the object has is + * dependent on the CPU model, number of cores, and page size of + * the machine. The actual size of the object will always be equal + * or greater than the specified +size+. + */ static VALUE init(VALUE self, VALUE size) { struct raindrops *r = get(self); @@ -87,7 +96,12 @@ retry: return self; } -/* :nodoc */ +/* + * call-seq: + * rd.dup -> rd_copy + * + * Duplicates and snapshots the current state of a Raindrops object. + */ static VALUE init_copy(VALUE dest, VALUE source) { struct raindrops *dst = get(dest); @@ -119,7 +133,13 @@ static unsigned long incr_decr_arg(int argc, const VALUE *argv) return argc == 2 ? NUM2ULONG(argv[1]) : 1; } -/* increments the value referred to by the +index+ constant by 1 */ +/* + * call-seq: + * rd.incr(index[, number]) -> result + * + * Increments the value referred to by the +index+ by +number+. + * +number+ defaults to +1+ if unspecified. + */ static VALUE incr(int argc, VALUE *argv, VALUE self) { unsigned long nr = incr_decr_arg(argc, argv); @@ -127,7 +147,13 @@ static VALUE incr(int argc, VALUE *argv, VALUE self) return ULONG2NUM(__sync_add_and_fetch(addr_of(self, argv[0]), nr)); } -/* decrements the value referred to by the +index+ constant by 1 */ +/* + * call-seq: + * rd.decr(index[, number]) -> result + * + * Decrements the value referred to by the +index+ by +number+. + * +number+ defaults to +1+ if unspecified. + */ static VALUE decr(int argc, VALUE *argv, VALUE self) { unsigned long nr = incr_decr_arg(argc, argv); @@ -135,7 +161,12 @@ static VALUE decr(int argc, VALUE *argv, VALUE self) return ULONG2NUM(__sync_sub_and_fetch(addr_of(self, argv[0]), nr)); } -/* converts the raindrops structure to an Array */ +/* + * call-seq: + * rd.to_ary -> Array + * + * converts the Raindrops structure to an Array + */ static VALUE to_ary(VALUE self) { struct raindrops *r = get(self); @@ -151,11 +182,25 @@ static VALUE to_ary(VALUE self) return rv; } +/* + * call-seq: + * rd.size -> Integer + * + * Returns the number of counters a Raindrops object can hold. Due to + * page alignment, this is always equal or greater than the number of + * requested slots passed to Raindrops.new + */ static VALUE size(VALUE self) { return LONG2NUM(get(self)->size); } +/* + * call-seq: + * rd[index] = value + * + * Assigns +value+ to the slot designated by +index+ + */ static VALUE aset(VALUE self, VALUE index, VALUE value) { unsigned long *addr = addr_of(self, index); @@ -165,6 +210,12 @@ static VALUE aset(VALUE self, VALUE index, VALUE value) return value; } +/* + * call-seq: + * rd[index] -> value + * + * Returns the value of the slot designated by +index+ + */ static VALUE aref(VALUE self, VALUE index) { return ULONG2NUM(*addr_of(self, index)); @@ -201,9 +252,19 @@ void Init_raindrops_ext(void) raindrop_size = (size_t)tmp; } #endif + + /* + * The size (in bytes) of a slot in a Raindrops object. + * This is the size of a word on single CPU systems and + * the size of the L1 cache line size if detectable. + * + * Defaults to 128 bytes if undetectable. + */ rb_define_const(cRaindrops, "SIZE", SIZET2NUM(raindrop_size)); - /* the maximum value a raindrop counter can hold */ + /* + * The maximum value a raindrop counter can hold + */ rb_define_const(cRaindrops, "MAX", ULONG2NUM((unsigned long)-1)); rb_define_alloc_func(cRaindrops, alloc); -- cgit v1.2.3-24-ge0c7