intruder 0.2.0 → 0.2.1

data/README.md

@@ -1,15 +1,119 @@
-**A little WIP again**
-
 What is it?
 ===========
 
 A ruby library with a C extension to interact with erlang processes.
-At the moment it's my fun project to get my feet wet with C. Stay tuned :)
+There's not much more than the ability to connect a node to a erlang
+process and then run some rpc calls.
+
+Want to use it?
+==========
+
+install it from gemcutter with `gem install intruder --source
+http://gemcutter.org`.
+
+Still interested?
+==========
+
+Glad you asked...
+First of all you need a node. A node is more or less your
+representative in the erlang world. You need to give it a name and it
+needs a cookie which basically manages your access rights.
+So for example if you wan't to communicate with a RabbitMQ process,
+you need to use the same magic cookie value as your RabbitMQ server
+does. Usually the erlang cookie is stored in the home directory in a
+hidden file called .erlang.cookie. Sometimes it can also be found in the
+application directory of your erlang application. Whatever...
+
+Let's try to get our feet wet and write a simple little echofunction
+in erlang. Here's the content of the file echo.erl:
+
+      -module(echo).
+      -export([say/1]).
+
+        say(Any) ->
+          {ok, Any}.
+
+Thats pretty basic stuff here. What we have here is a module called
+"echo" with a function called "say" that just returns a tuple of ok plus whatever arguments it was
+called with. Now open your erlang shell with `erl -sname funkyzeit`
+in the same directory as your echo.erl file is located and type
+`c(echo).` (including the dot) into the console. Now you have a node
+named "funkyzeit" running which knows about a module called "echo".
+
+But back to ruby. Open another console and fire up irb:
+
+First we wan't to create the node (assuming that the .erlang.cookie
+file is located at '~/.erlang.cookie').
+
+    require 'rubygems'
+    require 'intruder'
+    node = Intruder::Node.new('my_node', File.read(File.expand_path('~/.erlang.cookie')))
+
+Great! Now connect that thing to the other erlang node we fired up
+earlier (replace <myhost> with your actual hostname.... skip the
+.local if you are a mac user).
+
+    node.connect('funkyzeit@myhost')
+
+You should be connected to the other node now. Let's create the
+arguments we gonna pass to the echo module now.
+
+    args = Intruder::Term.encode([[:a, :b, :c]])
+
+Intruder::Term.encode is able to create Intruder Terms like lists,
+atoms, and "strings" if you pass them in as arrays, atoms or strings
+(or combinations of them). If you need a tuple or a binary you need to
+create them with `Intruder::Binary.new("mybinaryvalue")` or
+`Intruder::Tuple.new([:a, :b])` for now. Maybe I'll come up with a
+cleverer solution for that later... Lets call the "say" method on the
+"echo" module now. Therefore we create a proxy object for the erlang
+module and let some super simple method missing magic call the
+function on that proxy.
+
+    echo = node.mod('echo')
+    response = echo.say(args)
+
+The response should be a tuple containing the atom 'ok' and our list
+of atoms we created with the Term.encode function earlier. Let's
+confirm that:
+
+    response
+    => {ok, [a, b]}
+    p response.class
+    => Intruder::Tuple
+    response[0].to_s
+    => "ok"
+    p response[1].class
+    => Intruder::List
+    p response[1][0]
+    => a
+
+I hope that explains enough to get the idea...
+
+Issues
+====
+
+Well the obvious one is the lack of functionality. For my purpose,
+being able to run rpc calls could already be enough, but there are way
+more things to add that are expsed via the erl_interface / ei C
+libraries.
+
+Test coverage is... well, let's not talk about that.
+
+Keeping nodes alive requires to constantly reply to ERL_TICK messages
+that might be send by the remote node. To handle that I'm currently
+using a "keep_alive" POSIX thread and mutexes and stuff. That's just
+because I'm a bloody noob at those kind of things (frankly, they scare
+me!). That might (hopefully) change soon.
+
+.. insert more issues here ...
 
-Want to try?
+Run an example?
 ============
 
-the test script makes an rpc call to a rabbitmq server and queries for its status.
+the test script makes an rpc call to a rabbitmq server and queries for
+its status (Note: the example assumes that you are running it from
+within a checked out and compiled version).
 
 * checkout the source
 * `ruby extconf.rb`
@@ -43,14 +147,20 @@ the script should print something similar to this:
 Why that?
 =========
 
-because thats a fun project to learn c and I need it for another project of mine (namely: paukul/humpty)
+because thats a fun project to learn c and I need it for humpty,
+another project of mine (find it on github as well).
 
-What works already?
-===================
+But your C code sucks big time!
+====================
 
-description missing... yet :)
+I know, I'm a C-n00b. Wan't to improve it? Contribute? Ah, Not
+interested? ok then stfu :)
 
 Erlix?
 ======
 
-is great, I also took some stuff from them. Afaik, Erlix uses erl_interface for most of its operations. erl_interface is limited to one connection only, I needed something to open multiple connections to multiple queues. Erlix is able to do a LOT more than Intruder at the moment, make sure to check it out as well!
+is great, I also took some stuff from them. Afaik, Erlix uses
+erl_interface for most of its operations. erl_interface is limited to
+one connection only, I needed something to open multiple connections
+to multiple queues. If thats fine for you, Erlix is able to do a LOT
+more than Intruder at the moment, make sure to check it out as well!

data/src/term.c

@@ -77,7 +77,7 @@ VALUE rb_value_from_binary(INTRUDER_TERM *iterm) {
   VALUE rValue;
   iterm->type = INTRUDER_TYPE_BINARY;
   rValue = Data_Wrap_Struct(IntruderBinary, 0, free_intruder_term, iterm);
-  return Qnil;
+  return rValue;
 }
 
 static ETERM *intruder_eterm_from_array(VALUE obj);

data/src/tuple.c

@@ -39,11 +39,17 @@ VALUE intruder_tuple_init(VALUE self, VALUE arr) {
 
 VALUE intruder_tuple_member_at(VALUE self, VALUE position) {
   INTRUDER_TERM *iterm;
+  Data_Get_Struct(self, INTRUDER_TERM, iterm);
+
   ETERM *member;
   int iPosition = NUM2INT(position);
-  Data_Get_Struct(self, INTRUDER_TERM, iterm);
-  member = erl_element(iPosition+1, iterm->eterm);
-  return rb_value_from_eterm(member);
+  int tuple_size = erl_size(iterm->eterm);
+  if (iPosition < 0 || tuple_size < iPosition+1) {
+    return Qnil;
+  } else {
+    member = erl_element(iPosition+1, iterm->eterm);
+    return rb_value_from_eterm(member);
+  }
 }
 
 VALUE intruder_tuple_length(VALUE self) {

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Pascal Friederich
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-11 00:00:00 +00:00
+date: 2010-03-11 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency