wise_omf 0.9 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c646960c311267d13f375733a6e9eeb8445d892
-  data.tar.gz: 987108e23efaa45458ad3cafd5f908e63f24b192
+  metadata.gz: 1c8e0758c700cc9980a2cd20165c0133a7538bbc
+  data.tar.gz: e6c00e7941afd772c5c7e6c9a147026e1b9f7951
 SHA512:
-  metadata.gz: c877157e684d0d8603af76c98ff868f7eebefd34e033e39750c6005dd79dc5b15e3831bdea753728edfb6de4bb093b1ee0c9fd25f05c2da549384cd7b5021c8e
-  data.tar.gz: 3efdae6ecfc627219897d5f9210706ff0f2fb8485c59dc2d59da8b0eae424bc25c07a4a474ebcce8b19ca599cb3ef75fd5bc8a3d6b978780df39612951acf4b1
+  metadata.gz: 5817c0124d767d1a89fc9e7c96377700e123e95207720f9f3910ed7291e7bfa0afd2e540a5f4eef292ad566f71418e490409ded3c20f28b4227d1c8ef08690da
+  data.tar.gz: 5b3a7c196405a0e32845f9da57836cf0016f8c024cbf7ee27b81ad6af25329d0fe85a996b2b6789c6018ee0a4342c343fa465aacd4c528ad06d8210048b2bd95

data/lib/wise_omf/client.rb

@@ -1,8 +1,11 @@
 require 'lrucache'
 require 'wise_omf/uid_helper'
 require 'yaml'
+require 'omf_common'
 module WiseOMF
   module Client
+
+    # The ExperimentHelper offers helper methods for the experiment.
     class ExperimentHelper
       @@random = Random.new
       @@uid_cache = LRUCache.new(ttl: 30.minutes)
@@ -10,6 +13,9 @@ module WiseOMF
 
       # Create an unique message id
       # NOTE: Message ids are guaranteed to be unique within 30 minutes.
+      #
+      # @return [Integer] an integer which can be used as messageUID.
+      #   This integer is guaranteed to be unique within 30 minutes.
       def self.messageUID
         uid = -1
         while true
@@ -36,6 +42,17 @@ module WiseOMF
       @group
       @default_callback
 
+
+      # Creates a new WiseGroup which handles an OmfEc::Group for the given name And connects the resource with the given uid.
+      # Speaking in OMF, the resource represented by the given uid becomes a member of the newly created Group.
+      # The WiseGroup encapsulates the OMF group and handles the proper registration of callbacks for configure and request messages.
+      #
+      # However, you are free to use the OmfEc::Group directly, but it's highly recommended to use a WiseGroup as helper.
+      #
+      # @param name [String] the name for the OmfEc::Group.
+      # @param uid [String] the uid of the resource represented by this group.
+      #
+      # @see OmfEc::Group
       def initialize(name, uid)
         @callback_cache = LRUCache.new(ttl: 30.minutes)
         @name = name
@@ -44,26 +61,24 @@ module WiseOMF
         OmfEc.experiment.add_group(group)
         group.add_resource(uid)
         @group = group
-
-        #@group = OmfEc::Group.new(uid, {unique: false}) { |g|
-        #  info "Created Group #{name}: #{g.to_yaml}"
-        #
-        #  #yield self unless block.nil?
-        #
-        #}
-        #OmfEc.experiment.add_group(@group)
-        #@group.add_resource(name)
-        warn "Finished init"
+        info "Finished intialization of WiseGroup (#{name})"
       end
 
-      def init_callback
-
-        while @group.topic.nil?
-          info "Delaying callback creation for 0.5 seconds"
-          sleep 0.5
+      # This method initializes the callback handler on the group topic.
+      # The topic might be nil direct after the intialization.
+      #
+      # @param block a block that should be called after initializing the topic callback
+      def init_callback(&block)
+        if @group.topic.nil?
+          info "Delaying callback creation for 1 seconds"
+          OmfCommon.el.after(1) {
+            info "Firing"
+            init_callback(&block)
+          }
+          return
         end
-        info "Setting message callback for #{self.name}"
-        @group.topic.on_message(:inform_status) { |msg|
+        info "Setting message callback for WiseGroup (#{self.name})"
+        @group.topic.on_message(:wise_group_callback_handler) { |msg|
           rid = msg.content.properties.requestId
           if rid.nil? && @@default_message_types.include?(msg.content.type)
             self.default_callback.call(msg) unless self.default_callback.nil?
@@ -78,9 +93,15 @@ module WiseOMF
             end
           end
         }
+        info "Callback: #{block}"
+        block.call(self) if block
 
       end
 
+      # Send a request message for the given property and callback
+      #
+      # @param property [String] the property to request
+      # @param &block the callback to be called for responses to this request
       def request(property, &block)
         mid = WiseOMF::Client::ExperimentHelper.messageUID
         unless block.nil?
@@ -90,6 +111,10 @@ module WiseOMF
         @group.topic.configure({property => mid})
       end
 
+      # Send a configure message for the given property and callback
+      #
+      # @param property [String] the property to configure
+      # @param &block the callback to be called for responses to this configuration attempt
       def configure(property, value, &block)
         mid = WiseOMF::Client::ExperimentHelper.messageUID
         unless block.nil?
@@ -98,6 +123,11 @@ module WiseOMF
         @group.topic.configure({property => {requestId: mid, value: value}})
       end
 
+      # This method translates calls to configure_xxx and request_xxx into proper FRCP messages (like in the OMF)
+      #
+      # @param name [String] the name of the method
+      # @param *args [Array] an array of arguments (empty for request_xxx, containing one argument for configure_xxx)
+      # @param &block a block which should be set as callback for the request/ configure message
       def method_missing(name, *args, &block)
         if name =~ /set_(.+)/
           configure($1, args[0], &block)
@@ -106,14 +136,23 @@ module WiseOMF
         end
       end
 
+      # Method for deleting a callback from the callback cache.
+      # After deleting the callback, it will not be called for messages arriving with the given requestId
+      #
+      # @param requestId [Integer] the requestId to delete the callback for
       def delete_callback(requestId)
         @callback_cache.delete(requestId)
       end
 
+      # Terminates this group (unsubscribes topic...)
+      def done
+        self.group.topic.unsubscribe(:wise_group_callback_handler)
+      end
+
     end
 
     # The reservation manager handles the creation and storage of node groups and stores all relevant information
-    # for the current experiment.
+    # for the current experiment. The manager is designed as factory, so that it only exists once in the experiment.
     # If you need to talk to a single node, call the ResverationManager.groupForNode(nodeUrn) method.
     # If you want a custom subset of nodes, call the ReservationManager.groupForNodes(nodeUrnArray) method.
     # For talking to all nodes, you can get the approprita group bei calling ReservationManager.allNodesGroup.
@@ -123,9 +162,19 @@ module WiseOMF
       @@nodeGroups
       @@reservationGroup
 
-      # Initializes the reservation manager class and creates all needed wise groups
+      # Initializes the reservation manager class and creates the following WiseGroups:
+      #   - The allNodesGroup (containing all nodes of this reservation)
+      #   - One node group for each single node
+      #   - One group for the reservation itself
       #
-      # TODO explain parameters here
+      # @param reservation [Hash] a hash explaining by the following YAML example:
+      #     ---
+      #     :secretReservationKeys:
+      #       - :nodeUrnPrefix: "urn:wisebed:uzl1:"
+      #         :key: "7601BE4781736B57BC6185D1AAF33A9F"
+      #       - :nodeUrnPrefix: "..."
+      #         :key: "..."
+      # @param nodeUrns [Set, Array] a set of node urns beeing part of this reservation.
       def self.init(reservation, nodeUrns)
         @@nodeGroups = {}
         @@reservation = reservation
@@ -155,30 +204,37 @@ module WiseOMF
             group = WiseOMF::Client::WiseGroup.new(name, groupId)
           end
           @@nodeGroups[groupId] = group
-          group.init_callback
-          group.group.topic.on_message(:wait_for_membership) { |msg|
-            if msg.properties.membership && msg.properties.membership.include?(group.group.address)
-              info "New group setup finished"
-              group.group.topic.on_message(:wait_for_membership) {}
-              #group.init_callback
-              block.call(group) if block
-            end
+          info 'Creating new group'
+          group.init_callback {
+            info 'Topic initialized'
+            group.group.topic.on_message(:wait_for_membership) { |msg|
+              info "Wait for Membership: #{msg.to_yaml}"
+              if msg.properties.membership && msg.properties.membership.include?(group.group.address)
+                info 'New group setup finished'
+                group.group.topic.unsubscribe(:wait_for_membership)
+                block.call(group) if block
+              end
 
+            }
+            @@reservationGroup.group.topic.create(:wisebed_node, {uid: groupId, urns: nodeUrns, membership: group.group.address})
           }
-          @@reservationGroup.group.topic.create(:wisebed_node, {uid: groupId, urns: nodeUrns, membership: group.group.address})
+
 
         end
       end
 
       # Returns a group to use when interacting with an arbitrary subset of the all nodes set
       #
-      # @param[Array, Set, #read] a list of nodes to get the group for.
+      # @param nodeUrns [Array, Set, #read] a list of nodes to get the group for.
+      # @return [WiseOMF::Client::WiseGroup] the WiseGroup for the node urns if one was found, nil otherwise
       def self.groupForNodes(nodeUrns)
         groupId = WiseOMFUtils::UIDHelper.node_group_uid(@@reservation, nodeUrns)
         @@nodeGroups[groupId]
       end
 
       # Returns a group to work with when interacting with all nodes of the reservation
+      #
+      # @return [WiseOMF::Client::WiseGroup] the group containing the resource representing all nodes in the reservation
       def self.allNodesGroup
         groupId = WiseOMFUtils::UIDHelper.node_group_uid(@@reservation, @@nodeUrns)
         if @@nodeGroups[groupId].nil?
@@ -191,6 +247,7 @@ module WiseOMF
       # Returns a WiseGroup to talk to. This group should be used for interacting with single nodes.
       #
       # @param[String, #read] the node urn
+      # @return[WiseOMF::Client::WiseGroup] the group for a single resource
       def self.groupForNode(nodeUrn)
         groupId = WiseOMFUtils::UIDHelper.node_group_uid(@@reservation, [nodeUrn])
         if @@nodeGroups[groupId].nil?
@@ -201,10 +258,19 @@ module WiseOMF
       end
 
       # Getter for the reservation id of the current reservation
+      # @return[String] the reservation id for this reservation
       def self.reservationID
         WiseOMFUtils::UIDHelper.reservation_uid(@@reservation)
       end
 
+      # Finalizes all node groups and the reservation group.
+      # Call this method at the end of your experiment just before calling OmfEc::Experiment.done
+      def self.done
+        info 'Cleaning Reservation Resources'
+        @@nodeGroups.each_value { |group| group.done }
+        @@reservationGroup.done
+      end
+
 
     end
   end

data/lib/wise_omf.rb

@@ -1,4 +1,8 @@
 require 'wise_omf/client'
 require 'wise_omf/protobuf'
+
+# The main file of the WiseOMF gem.
+# This class just requires the Client Modul which should be used on client side
+# @see WiseOMF::Client
 class WiseOmf
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wise_omf
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: 0.9.1
 platform: ruby
 authors:
 - Tobias Mende
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-19 00:00:00.000000000 Z
+date: 2013-11-20 00:00:00.000000000 Z
 dependencies: []
 description: This gem provides helpers for working with the testbed runtime via the
   OMF (Orbit Measurement Framework)
@@ -46,3 +46,4 @@ signing_key:
 specification_version: 4
 summary: WiseOMF Utility Gem
 test_files: []
+has_rdoc: