sfml3-rb 0.2.2 → 0.3.1

data/ext/network/tcp_listener.c

@@ -9,13 +9,13 @@
 #include "network/tcp_socket.h"
 
 typedef struct {
-    sfTcpListener *handle;
+    sfTcpListener* handle;
 } TcpListener;
 
 static VALUE rb_cTcpListener;
 
-static void TcpListener_free(void *ptr) {
-    TcpListener *listener = ptr;
+static void TcpListener_free(void* ptr) {
+    TcpListener* listener = ptr;
 
     if (listener->handle != NULL) {
         sfTcpListener_destroy(listener->handle);
@@ -27,11 +27,10 @@ static void TcpListener_free(void *ptr) {
 static const rb_data_type_t TcpListener_data_type = {
     .wrap_struct_name = "SFML::TcpListener",
     .function = {.dmark = NULL, .dfree = TcpListener_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE TcpListener_wrap(VALUE klass, sfTcpListener *handle) {
-    TcpListener *ptr;
+static VALUE TcpListener_wrap(VALUE klass, sfTcpListener* handle) {
+    TcpListener* ptr;
 
     if (handle == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create TCP listener");
@@ -43,44 +42,104 @@ static VALUE TcpListener_wrap(VALUE klass, sfTcpListener *handle) {
     return TypedData_Wrap_Struct(klass, &TcpListener_data_type, ptr);
 }
 
-static VALUE TcpListener_new(VALUE klass) {
+static VALUE TcpListener_alloc(VALUE klass) {
     return TcpListener_wrap(klass, sfTcpListener_create());
 }
 
+/* call-seq:
+ *   TcpListener.new -> TcpListener
+ *
+ * Creates a new TCP listener that is not yet listening.
+ *
+ * @return [TcpListener]
+ */
+static VALUE TcpListener_initialize(VALUE self) {
+    return self;
+}
+
+/* call-seq:
+ *   TcpListener.any_port -> Integer
+ *
+ * Returns the port value that makes #listen bind to an OS-chosen port.
+ *
+ * @return [Integer] a port value that #listen interprets as "let the OS
+ *   pick an available port"
+ */
 static VALUE TcpListener_any_port(VALUE klass) {
     return UINT2NUM(sfTcpListener_anyPort());
 }
 
+/* call-seq: blocking? -> true or false
+ *
+ * Returns +true+ if the listener is in blocking mode.
+ *
+ * @return [Boolean]
+ */
 static VALUE TcpListener_blocking(VALUE self) {
     return BOOL2RB(sfTcpListener_isBlocking(Get_TcpListener_Struct(self)));
 }
 
+/* call-seq:
+ *   blocking=(value) -> value
+ *
+ * Enables or disables blocking mode according to +value+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE TcpListener_set_blocking(VALUE self, VALUE rb_value) {
     sfTcpListener_setBlocking(Get_TcpListener_Struct(self), RTEST(rb_value));
     return rb_value;
 }
 
+/* call-seq: local_port -> Integer
+ *
+ * Returns the port the listener is bound to, or 0 if it isn't listening.
+ *
+ * @return [Integer] the port the listener is bound to, or 0 if it isn't
+ *   listening
+ */
 static VALUE TcpListener_local_port(VALUE self) {
     return UINT2NUM(sfTcpListener_getLocalPort(Get_TcpListener_Struct(self)));
 }
 
-static VALUE TcpListener_listen(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   listen(port, address = IpAddress::ANY) -> Symbol
+ *
+ * Starts listening for incoming connections on +port+, optionally
+ * restricted to a specific local network interface via +address+.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
+static VALUE TcpListener_listen(int argc, VALUE* argv, VALUE self) {
     VALUE rb_port, rb_address;
 
     rb_scan_args(argc, argv, "11", &rb_port, &rb_address);
 
-    return ID2SYM(rb_intern(socket_status_name(sfTcpListener_listen(
-        Get_TcpListener_Struct(self), (unsigned short) NUM2INT(rb_port),
-        ip_address_from_rb(rb_address, sfIpAddress_Any)))));
+    return ID2SYM(rb_intern(socket_status_name(
+        sfTcpListener_listen(Get_TcpListener_Struct(self), (unsigned short)NUM2INT(rb_port),
+                             ip_address_from_rb(rb_address, sfIpAddress_Any)))));
 }
 
+/* call-seq: close -> self
+ *
+ * Stops listening and closes the underlying socket.
+ *
+ * @return [self]
+ */
 static VALUE TcpListener_close(VALUE self) {
     sfTcpListener_close(Get_TcpListener_Struct(self));
     return self;
 }
 
+/* call-seq: accept -> [TcpSocket, Symbol]
+ *
+ * Blocks (unless #blocking? is +false+) waiting for a client to connect.
+ *
+ * @return [Array(TcpSocket, Symbol)] the connected socket (or +nil+ if the
+ *   status isn't +:done+), and a SocketStatus name
+ */
 static VALUE TcpListener_accept(VALUE self) {
-    sfTcpSocket *socket = NULL;
+    sfTcpSocket* socket = NULL;
     sfSocketStatus status = sfTcpListener_accept(Get_TcpListener_Struct(self), &socket);
     VALUE rb_result = rb_ary_new_capa(2);
 
@@ -90,10 +149,15 @@ static VALUE TcpListener_accept(VALUE self) {
     return rb_result;
 }
 
-void Init_TcpListener(VALUE rb_module) {
-    rb_cTcpListener = rb_define_class_under(rb_module, "TcpListener", rb_cObject);
+/* Document-class: SFML::TcpListener
+ * Listens for and accepts incoming TCP connections, producing connected
+ * TcpSocket instances.
+ */
+void Init_TcpListener(VALUE rb_mSFML) {
+    rb_cTcpListener = rb_define_class_under(rb_mSFML, "TcpListener", rb_cObject);
+    rb_define_alloc_func(rb_cTcpListener, TcpListener_alloc);
 
-    rb_define_singleton_method(rb_cTcpListener, "new", TcpListener_new, 0);
+    rb_define_method(rb_cTcpListener, "initialize", TcpListener_initialize, 0);
     rb_define_singleton_method(rb_cTcpListener, "any_port", TcpListener_any_port, 0);
 
     rb_define_method(rb_cTcpListener, "blocking?", TcpListener_blocking, 0);
@@ -108,8 +172,8 @@ VALUE Get_Klass_TcpListener(void) {
     return rb_cTcpListener;
 }
 
-void *Get_TcpListener_Struct(VALUE self) {
-    TcpListener *ptr;
+void* Get_TcpListener_Struct(VALUE self) {
+    TcpListener* ptr;
     TypedData_Get_Struct(self, TcpListener, &TcpListener_data_type, ptr);
     return ptr->handle;
 }

data/ext/network/tcp_socket.c

@@ -10,13 +10,13 @@
 #include "system/time.h"
 
 typedef struct {
-    sfTcpSocket *handle;
+    sfTcpSocket* handle;
 } TcpSocket;
 
 static VALUE rb_cTcpSocket;
 
-static void TcpSocket_free(void *ptr) {
-    TcpSocket *socket = ptr;
+static void TcpSocket_free(void* ptr) {
+    TcpSocket* socket = ptr;
 
     if (socket->handle != NULL) {
         sfTcpSocket_destroy(socket->handle);
@@ -28,11 +28,10 @@ static void TcpSocket_free(void *ptr) {
 static const rb_data_type_t TcpSocket_data_type = {
     .wrap_struct_name = "SFML::TcpSocket",
     .function = {.dmark = NULL, .dfree = TcpSocket_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE TcpSocket_wrap(VALUE klass, sfTcpSocket *handle) {
-    TcpSocket *ptr;
+static VALUE TcpSocket_wrap(VALUE klass, sfTcpSocket* handle) {
+    TcpSocket* ptr;
 
     if (handle == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create TCP socket");
@@ -44,36 +43,88 @@ static VALUE TcpSocket_wrap(VALUE klass, sfTcpSocket *handle) {
     return TypedData_Wrap_Struct(klass, &TcpSocket_data_type, ptr);
 }
 
-VALUE tcp_socket_from_handle(sfTcpSocket *socket) {
+VALUE tcp_socket_from_handle(sfTcpSocket* socket) {
     return TcpSocket_wrap(rb_cTcpSocket, socket);
 }
 
-static VALUE TcpSocket_new(VALUE klass) {
+static VALUE TcpSocket_alloc(VALUE klass) {
     return TcpSocket_wrap(klass, sfTcpSocket_create());
 }
 
+/* call-seq:
+ *   TcpSocket.new -> TcpSocket
+ *
+ * Creates a new, unconnected TCP socket.
+ *
+ * @return [TcpSocket] a new, unconnected socket
+ */
+static VALUE TcpSocket_initialize(VALUE self) {
+    return self;
+}
+
+/* call-seq: blocking? -> true or false
+ *
+ * Returns +true+ if the socket is in blocking mode.
+ *
+ * @return [Boolean]
+ */
 static VALUE TcpSocket_blocking(VALUE self) {
     return BOOL2RB(sfTcpSocket_isBlocking(Get_TcpSocket_Struct(self)));
 }
 
+/* call-seq:
+ *   blocking=(value) -> value
+ *
+ * Enables or disables blocking mode according to +value+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE TcpSocket_set_blocking(VALUE self, VALUE rb_value) {
     sfTcpSocket_setBlocking(Get_TcpSocket_Struct(self), RTEST(rb_value));
     return rb_value;
 }
 
+/* call-seq: local_port -> Integer
+ *
+ * Returns the local port the socket is bound to.
+ *
+ * @return [Integer] the local port the socket is bound to, or 0 if it
+ *   isn't connected
+ */
 static VALUE TcpSocket_local_port(VALUE self) {
     return UINT2NUM(sfTcpSocket_getLocalPort(Get_TcpSocket_Struct(self)));
 }
 
+/* call-seq: remote_address -> IpAddress
+ *
+ * Returns the address of the remote peer.
+ *
+ * @return [IpAddress] the address of the remote peer, or +IpAddress::NONE+
+ *   if not connected
+ */
 static VALUE TcpSocket_remote_address(VALUE self) {
     return ip_address_to_rb(sfTcpSocket_getRemoteAddress(Get_TcpSocket_Struct(self)));
 }
 
+/* call-seq: remote_port -> Integer
+ *
+ * Returns the port of the remote peer.
+ *
+ * @return [Integer] the port of the remote peer, or 0 if not connected
+ */
 static VALUE TcpSocket_remote_port(VALUE self) {
     return UINT2NUM(sfTcpSocket_getRemotePort(Get_TcpSocket_Struct(self)));
 }
 
-static VALUE TcpSocket_connect(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   connect(address, port, timeout = Time.zero) -> Symbol
+ *
+ * Connects to a remote peer, blocking (unless #blocking? is +false+) until
+ * connected or +timeout+ elapses.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
+static VALUE TcpSocket_connect(int argc, VALUE* argv, VALUE self) {
     VALUE rb_address, rb_port, rb_timeout;
     sfTime timeout = sfTime_Zero;
 
@@ -85,22 +136,45 @@ static VALUE TcpSocket_connect(int argc, VALUE *argv, VALUE self) {
 
     return ID2SYM(rb_intern(socket_status_name(sfTcpSocket_connect(
         Get_TcpSocket_Struct(self), ip_address_from_rb(rb_address, sfIpAddress_None),
-        (unsigned short) NUM2INT(rb_port), timeout))));
+        (unsigned short)NUM2INT(rb_port), timeout))));
 }
 
+/* call-seq: disconnect -> self
+ *
+ * Closes the connection.
+ *
+ * @return [self]
+ */
 static VALUE TcpSocket_disconnect(VALUE self) {
     sfTcpSocket_disconnect(Get_TcpSocket_Struct(self));
     return self;
 }
 
+/* call-seq:
+ *   send(data) -> Symbol
+ *
+ * Sends the full contents of +data+, blocking (unless #blocking? is
+ * +false+) until it is all sent. Prefer #send_partial for non-blocking
+ * sockets, since this can return +:not_ready+ having sent only part of
+ * the data with no way to know how much.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
 static VALUE TcpSocket_send(VALUE self, VALUE rb_data) {
     StringValue(rb_data);
 
-    return ID2SYM(rb_intern(socket_status_name(
-        sfTcpSocket_send(Get_TcpSocket_Struct(self), RSTRING_PTR(rb_data),
-                         (size_t) RSTRING_LEN(rb_data)))));
+    return ID2SYM(rb_intern(socket_status_name(sfTcpSocket_send(
+        Get_TcpSocket_Struct(self), RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)))));
 }
 
+/* call-seq:
+ *   send_partial(data) -> [Integer, Symbol]
+ *
+ * Like #send, but may send only part of +data+ and reports how much.
+ *
+ * @return [Array(Integer, Symbol)] the number of bytes actually sent, and
+ *   a SocketStatus name
+ */
 static VALUE TcpSocket_send_partial(VALUE self, VALUE rb_data) {
     size_t sent = 0;
     sfSocketStatus status;
@@ -109,7 +183,7 @@ static VALUE TcpSocket_send_partial(VALUE self, VALUE rb_data) {
     StringValue(rb_data);
 
     status = sfTcpSocket_sendPartial(Get_TcpSocket_Struct(self), RSTRING_PTR(rb_data),
-                                     (size_t) RSTRING_LEN(rb_data), &sent);
+                                     (size_t)RSTRING_LEN(rb_data), &sent);
 
     rb_result = rb_ary_new_capa(2);
     rb_ary_push(rb_result, SIZET2NUM(sent));
@@ -118,12 +192,19 @@ static VALUE TcpSocket_send_partial(VALUE self, VALUE rb_data) {
     return rb_result;
 }
 
-/* Receive needs a maximum size up front because CSFML fills a caller buffer.
-   Returns [data, status], where data is empty unless the status is :done. */
-static VALUE TcpSocket_receive(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   receive(max_length = 1024) -> [String, Symbol]
+ *
+ * Receive needs a maximum size up front because CSFML fills a caller buffer.
+ * Returns [data, status], where data is empty unless the status is :done.
+ *
+ * @return [Array(String, Symbol)] the bytes received, and a SocketStatus name
+ * @raise [ArgumentError] if +max_length+ isn't positive
+ */
+static VALUE TcpSocket_receive(int argc, VALUE* argv, VALUE self) {
     VALUE rb_max_length;
     long max_length = 1024;
-    char *buffer;
+    char* buffer;
     size_t received = 0;
     sfSocketStatus status;
     VALUE rb_result;
@@ -138,12 +219,16 @@ static VALUE TcpSocket_receive(int argc, VALUE *argv, VALUE self) {
         rb_raise(rb_eArgError, "maximum length must be positive");
     }
 
-    buffer = malloc((size_t) max_length);
+    buffer = malloc((size_t)max_length);
+
+    if (buffer == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate receive buffer");
+    }
 
-    status = sfTcpSocket_receive(Get_TcpSocket_Struct(self), buffer, (size_t) max_length, &received);
+    status = sfTcpSocket_receive(Get_TcpSocket_Struct(self), buffer, (size_t)max_length, &received);
 
     rb_result = rb_ary_new_capa(2);
-    rb_ary_push(rb_result, rb_str_new(buffer, (long) received));
+    rb_ary_push(rb_result, rb_str_new(buffer, (long)received));
     rb_ary_push(rb_result, ID2SYM(rb_intern(socket_status_name(status))));
 
     free(buffer);
@@ -151,6 +236,14 @@ static VALUE TcpSocket_receive(int argc, VALUE *argv, VALUE self) {
     return rb_result;
 }
 
+/* call-seq:
+ *   send_packet(packet) -> Symbol
+ *
+ * Sends +packet+ over the connection.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE TcpSocket_send_packet(VALUE self, VALUE rb_packet) {
     if (!rb_obj_is_kind_of(rb_packet, Get_Klass_Packet())) {
         rb_raise(rb_eTypeError, "expected an SFML::Packet");
@@ -160,6 +253,15 @@ static VALUE TcpSocket_send_packet(VALUE self, VALUE rb_packet) {
         sfTcpSocket_sendPacket(Get_TcpSocket_Struct(self), Get_Packet_Struct(rb_packet)))));
 }
 
+/* call-seq:
+ *   receive_packet(packet) -> Symbol
+ *
+ * Fills +packet+ (replacing its previous contents) with the next packet
+ * received.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE TcpSocket_receive_packet(VALUE self, VALUE rb_packet) {
     if (!rb_obj_is_kind_of(rb_packet, Get_Klass_Packet())) {
         rb_raise(rb_eTypeError, "expected an SFML::Packet");
@@ -169,10 +271,16 @@ static VALUE TcpSocket_receive_packet(VALUE self, VALUE rb_packet) {
         sfTcpSocket_receivePacket(Get_TcpSocket_Struct(self), Get_Packet_Struct(rb_packet)))));
 }
 
-void Init_TcpSocket(VALUE rb_module) {
-    rb_cTcpSocket = rb_define_class_under(rb_module, "TcpSocket", rb_cObject);
+/* Document-class: SFML::TcpSocket
+ * A connection-oriented, reliable, byte-stream socket for TCP communication.
+ * Connect with #connect (or receive one already connected from
+ * TcpListener#accept), then send/receive raw bytes or Packet instances.
+ */
+void Init_TcpSocket(VALUE rb_mSFML) {
+    rb_cTcpSocket = rb_define_class_under(rb_mSFML, "TcpSocket", rb_cObject);
+    rb_define_alloc_func(rb_cTcpSocket, TcpSocket_alloc);
 
-    rb_define_singleton_method(rb_cTcpSocket, "new", TcpSocket_new, 0);
+    rb_define_method(rb_cTcpSocket, "initialize", TcpSocket_initialize, 0);
 
     rb_define_method(rb_cTcpSocket, "blocking?", TcpSocket_blocking, 0);
     rb_define_method(rb_cTcpSocket, "blocking=", TcpSocket_set_blocking, 1);
@@ -192,8 +300,8 @@ VALUE Get_Klass_TcpSocket(void) {
     return rb_cTcpSocket;
 }
 
-void *Get_TcpSocket_Struct(VALUE self) {
-    TcpSocket *ptr;
+void* Get_TcpSocket_Struct(VALUE self) {
+    TcpSocket* ptr;
     TypedData_Get_Struct(self, TcpSocket, &TcpSocket_data_type, ptr);
     return ptr->handle;
 }