close #25, #179: mechanism to retrieve seized amounts and release all (…

…#180)

* return immediately if seize/release amount=0

* provide get_seized method

* implementation of #25

* update docs

* implementation of #179

* don't allow negative id for get_*_selected

* some refactoring

* fix test

* update NEWS

* add tests

NAMESPACE

@@ -37,6 +37,8 @@ S3method(get_queue_size,wrap)
 S3method(get_queue_size_selected,simmer)
 S3method(get_resources,simmer)
 S3method(get_resources,wrap)
+S3method(get_seized,simmer)
+S3method(get_seized_selected,simmer)
 S3method(get_selected,simmer)
 S3method(get_server_count,simmer)
 S3method(get_server_count,wrap)
@@ -54,7 +56,9 @@ S3method(now,wrap)
 S3method(peek,simmer)
 S3method(peek,wrap)
 S3method(release,trajectory)
+S3method(release_all,trajectory)
 S3method(release_selected,trajectory)
+S3method(release_selected_all,trajectory)
 S3method(renege_abort,trajectory)
 S3method(renege_if,trajectory)
 S3method(renege_in,trajectory)
@@ -112,6 +116,8 @@ export(get_queue_count_selected)
 export(get_queue_size)
 export(get_queue_size_selected)
 export(get_resources)
+export(get_seized)
+export(get_seized_selected)
 export(get_selected)
 export(get_server_count)
 export(get_server_count_selected)
@@ -128,7 +134,9 @@ export(monitor_mem)
 export(now)
 export(peek)
 export(release)
+export(release_all)
 export(release_selected)
+export(release_selected_all)
 export(renege_abort)
 export(renege_if)
 export(renege_in)

NEWS.md

@@ -6,12 +6,17 @@
   arrivals, i.e., those dropped from a resource (due to preemption, resource
   shrinkage or a rejected `seize`) or those that `leave` a trajectory (#178
   addressing #177).
+- New `release_all()` and `release_selected_all()` activities automatically
+  retrieve the amount of resources seized and release it (#180 addressing #25).
+- New `get_seized()` and `get_seized_selected()` getters allow an arrival to
+  retrieve the amount of resources seized (#180 addressing #179).
 
 ## Minor changes and fixes:
 
 - Fix performance issues in data sources (#176).
 - Update CITATION.
 - Fix monitored activity for preempted arrivals (as part of #178).
+- Fix seizes/releases with a null amount (as part of #180).
 
 # simmer 4.1.0
 

R/RcppExports.R

@@ -25,6 +25,14 @@ Release__new_func <- function(resource, amount) {
     .Call(`_simmer_Release__new_func`, resource, amount)
 }
 
+ReleaseAll__new <- function(resource) {
+    .Call(`_simmer_ReleaseAll__new`, resource)
+}
+
+ReleaseAll__new_void <- function() {
+    .Call(`_simmer_ReleaseAll__new_void`)
+}
+
 ReleaseSelected__new <- function(id, amount) {
     .Call(`_simmer_ReleaseSelected__new`, id, amount)
 }
@@ -33,6 +41,10 @@ ReleaseSelected__new_func <- function(id, amount) {
     .Call(`_simmer_ReleaseSelected__new_func`, id, amount)
 }
 
+ReleaseSelectedAll__new <- function(id) {
+    .Call(`_simmer_ReleaseSelectedAll__new`, id)
+}
+
 SetCapacity__new <- function(resource, value, mod) {
     .Call(`_simmer_SetCapacity__new`, resource, value, mod)
 }
@@ -365,6 +377,14 @@ get_queue_count_selected_ <- function(sim_, id) {
     .Call(`_simmer_get_queue_count_selected_`, sim_, id)
 }
 
+get_seized_ <- function(sim_, names) {
+    .Call(`_simmer_get_seized_`, sim_, names)
+}
+
+get_seized_selected_ <- function(sim_, id) {
+    .Call(`_simmer_get_seized_selected_`, sim_, id)
+}
+
 get_selected_ <- function(sim_, id) {
     .Call(`_simmer_get_selected_`, sim_, id)
 }

R/simmer-class.R

@@ -250,7 +250,7 @@ Simmer <- R6Class("simmer",
     get_prioritization = function() get_prioritization_(private$sim_obj),
 
     get_capacity = function(resources, id=0) {
-      check_args(resources=c("string vector", "NULL"), id="numeric")
+      check_args(resources=c("string vector", "NULL"), id="number")
       ret <- switch(
         binarise(is.null(resources)),
         get_capacity_(private$sim_obj, resources),
@@ -260,7 +260,7 @@ Simmer <- R6Class("simmer",
     },
 
     get_queue_size = function(resources, id=0) {
-      check_args(resources=c("string vector", "NULL"), id="numeric")
+      check_args(resources=c("string vector", "NULL"), id="number")
       ret <- switch(
         binarise(is.null(resources)),
         get_queue_size_(private$sim_obj, resources),
@@ -270,7 +270,7 @@ Simmer <- R6Class("simmer",
     },
 
     get_server_count = function(resources, id=0) {
-      check_args(resources=c("string vector", "NULL"), id="numeric")
+      check_args(resources=c("string vector", "NULL"), id="number")
       switch(
         binarise(is.null(resources)),
         get_server_count_(private$sim_obj, resources),
@@ -279,16 +279,25 @@ Simmer <- R6Class("simmer",
     },
 
     get_queue_count = function(resources, id=0) {
-      check_args(resources=c("string vector", "NULL"), id="numeric")
+      check_args(resources=c("string vector", "NULL"), id="number")
       ret <- switch(
         binarise(is.null(resources)),
         get_queue_count_(private$sim_obj, resources),
         get_queue_count_selected_(private$sim_obj, id)
       )
     },
 
+    get_seized = function(resources, id=0) {
+      check_args(resources=c("string vector", "NULL"), id="number")
+      ret <- switch(
+        binarise(is.null(resources)),
+        get_seized_(private$sim_obj, resources),
+        get_seized_selected_(private$sim_obj, id)
+      )
+    },
+
     get_selected = function(id=0) {
-      check_args(id="numeric")
+      check_args(id="number")
       get_selected_(private$sim_obj, id)
     },
 

R/simmer-methods.R

@@ -40,13 +40,14 @@
 #' \code{\link{get_server_count}}, \code{\link{get_queue_count}},
 #' \code{\link{get_capacity_selected}}, \code{\link{get_queue_size_selected}},
 #' \code{\link{get_server_count_selected}}, \code{\link{get_queue_count_selected}},
+#' \code{\link{get_seized}}, \code{\link{get_seized_selected}},
 #' \code{\link{get_selected}}
 #'
 #' \item Sources: \code{\link{add_generator}}, \code{\link{add_dataframe}},
 #' \code{\link{get_sources}}, \code{\link{get_n_generated}},
 #' \code{\link{get_trajectory}}
 #'
-#' \item Globals: \code{\link{add_global}}, \code{\link{get_global}}.
+#' \item Globals: \code{\link{add_global}}, \code{\link{get_global}}
 #'
 #' \item Data retrieval: \code{\link{get_mon_arrivals}},
 #' \code{\link{get_mon_attributes}}, \code{\link{get_mon_resources}}
@@ -436,12 +437,12 @@ get_prioritization.simmer <- function(.env) .env$get_prioritization()
 
 #' Get Resource Parameters
 #'
-#' Getters for resources: server capacity/count and queue size/count.
+#' Getters for resources: server capacity/count and queue size/count, seized
+#' amount and selected resources.
 #'
 #' @inheritParams reset
+#' @inheritParams select
 #' @param resources one or more resource names.
-#' @param id selection identifier (a negative number causes the function to
-#' return the required parameter for all the selected resources).
 #'
 #' @return Return a vector (character for \code{get_selected}, numeric for the
 #' rest of them).
@@ -502,6 +503,20 @@ get_queue_count_selected <- function(.env, id=0) UseMethod("get_queue_count_sele
 #' @export
 get_queue_count_selected.simmer <- function(.env, id=0) .env$get_queue_count(NULL, id)
 
+#' @rdname get_capacity
+#' @export
+get_seized <- function(.env, resources) UseMethod("get_seized")
+
+#' @export
+get_seized.simmer <- function(.env, resources) .env$get_seized(resources)
+
+#' @rdname get_capacity
+#' @export
+get_seized_selected <- function(.env, id=0) UseMethod("get_seized_selected")
+
+#' @export
+get_seized_selected.simmer <- function(.env, id=0) .env$get_seized(NULL, id)
+
 #' @rdname get_capacity
 #' @export
 get_selected <- function(.env, id=0) UseMethod("get_selected")

R/trajectory-activities.R

@@ -73,6 +73,20 @@ release_selected <- function(.trj, amount=1, id=0) UseMethod("release_selected")
 #' @export
 release_selected.trajectory <- function(.trj, amount=1, id=0) .trj$release(NA, amount, id)
 
+#' @rdname seize
+#' @export
+release_all <- function(.trj, resource) UseMethod("release_all")
+
+#' @export
+release_all.trajectory <- function(.trj, resource) .trj$release(resource, NA)
+
+#' @rdname seize
+#' @export
+release_selected_all <- function(.trj, id=0) UseMethod("release_selected_all")
+
+#' @export
+release_selected_all.trajectory <- function(.trj, id=0) .trj$release(NA, NA, id)
+
 #' Set Resource Parameters
 #'
 #' Activities for modifying a resource's server capacity or queue size, by name

R/trajectory-class.R

@@ -125,11 +125,19 @@ Trajectory <- R6Class("trajectory",
     },
 
     release = function(resource, amount=1, id=0) {
-      check_args(resource=c("string", "NA"), amount=c("number", "function"), id="number")
+      if (missing(resource))
+        return(private$add_activity(ReleaseAll__new_void()))
+      check_args(
+        resource = c("string", "NA"),
+        amount = c("number", "function", "NA"),
+        id = "number"
+      )
       switch(
-        binarise(is.na(resource), is.function(amount)),
+        binarise(is.na(resource), is.na(amount), is.function(amount)),
         private$add_activity(Release__new(resource, amount)),
         private$add_activity(ReleaseSelected__new(id, amount)),
+        private$add_activity(ReleaseAll__new(resource)),
+        private$add_activity(ReleaseSelectedAll__new(id)),
         private$add_activity(Release__new_func(resource, amount)),
         private$add_activity(ReleaseSelected__new_func(id, amount))
       )

R/trajectory-methods.R

@@ -40,9 +40,10 @@
 #' \code{\link{set_prioritization}}
 #'
 #' \item Interaction with resources: \code{\link{select}}, \code{\link{seize}},
-#' \code{\link{release}}, \code{\link{seize_selected}}, \code{\link{release_selected}},
-#' \code{\link{set_capacity}}, \code{\link{set_queue_size}}, \code{\link{set_capacity_selected}},
-#' \code{\link{set_queue_size_selected}}
+#' \code{\link{release}}, \code{\link{release_all}}, \code{\link{seize_selected}},
+#' \code{\link{release_selected}}, \code{\link{release_selected_all}},
+#' \code{\link{set_capacity}}, \code{\link{set_queue_size}},
+#' \code{\link{set_capacity_selected}}, \code{\link{set_queue_size_selected}}
 #'
 #' \item Interaction with generators: \code{\link{activate}}, \code{\link{deactivate}},
 #' \code{\link{set_trajectory}}, \code{\link{set_source}}
@@ -56,8 +57,8 @@
 #' \item Asynchronous programming: \code{\link{send}}, \code{\link{trap}},
 #' \code{\link{untrap}}, \code{\link{wait}}
 #'
-#' \item Reneging: \code{\link{leave}}, \code{\link{renege_in}}, \code{\link{renege_if}},
-#' \code{\link{renege_abort}}
+#' \item Reneging: \code{\link{leave}}, \code{\link{handle_unfinished}},
+#' \code{\link{renege_in}}, \code{\link{renege_if}}, \code{\link{renege_abort}}
 #'
 #' }
 #'

inst/include/simmer/activity/resource.h

@@ -41,7 +41,7 @@ namespace simmer {
     Seize(int id, const T& amount, const VEC<bool>& cont,
           const VEC<REnv>& trj, unsigned short mask)
       : Fork("Seize", cont, trj),
-        internal::ResGetter("Seize", "[]", id), amount(amount), mask(mask) {}
+        internal::ResGetter("Seize", id), amount(amount), mask(mask) {}
 
     void print(unsigned int indent = 0, bool verbose = false, bool brief = false) {
       Activity::print(indent, verbose, brief);
@@ -50,8 +50,8 @@ namespace simmer {
     }
 
     double run(Arrival* arrival) {
-      return select_path(
-        arrival, get_resource(arrival)->seize(arrival, std::abs(get<int>(amount, arrival))));
+      return select_path(arrival, get_resource(arrival)->
+                         seize(arrival, std::abs(get<int>(amount, arrival))));
     }
 
   protected:
@@ -86,25 +86,41 @@ namespace simmer {
   public:
     CLONEABLE(Release<T>)
 
-    Release(const std::string& resource, const T& amount)
+    Release()
+      : Activity("Release", PRIORITY_RELEASE),
+        internal::ResGetter("Release"), amount(NONE) {}
+
+    Release(const std::string& resource, const OPT<T>& amount = NONE)
       : Activity("Release", PRIORITY_RELEASE),
         internal::ResGetter("Release", resource), amount(amount) {}
 
-    Release(int id, const T& amount)
+    Release(int id, const OPT<T>& amount = NONE)
       : Activity("Release", PRIORITY_RELEASE),
-        internal::ResGetter("Release", "[]", id), amount(amount) {}
+        internal::ResGetter("Release", id), amount(amount) {}
 
     void print(unsigned int indent = 0, bool verbose = false, bool brief = false) {
       Activity::print(indent, verbose, brief);
-      internal::print(brief, true, ARG(resource), ARG(amount));
+      if (amount)
+        internal::print(brief, true, ARG(resource), "amount: ", *amount);
+      else internal::print(brief, true, ARG(resource), "amount: ", "all");
     }
 
     double run(Arrival* arrival) {
-      return get_resource(arrival)->release(arrival, std::abs(get<int>(amount, arrival)));
+      if (Resource* res = get_resource(arrival)) {
+        if (amount)
+          return res->release(arrival, std::abs(get<int>(*amount, arrival)));
+        return res->release(arrival, res->get_seized(arrival));
+      }
+
+      foreach_ (const std::string& resource, arrival->sim->get_resources()) {
+        Resource* res = arrival->sim->get_resource(resource);
+        res->release(arrival, res->get_seized(arrival));
+      }
+      return 0;
     }
 
   protected:
-    T amount;
+    OPT<T> amount;
   };
 
   /**
@@ -120,7 +136,7 @@ namespace simmer {
         value(value), mod(mod), op(internal::get_op<double>(mod)) {}
 
     SetCapacity(int id, const T& value, char mod='N')
-      : Activity("SetCapacity"), internal::ResGetter("SetCapacity", "[]", id),
+      : Activity("SetCapacity"), internal::ResGetter("SetCapacity", id),
         value(value), mod(mod), op(internal::get_op<double>(mod)) {}
 
     void print(unsigned int indent = 0, bool verbose = false, bool brief = false) {
@@ -161,7 +177,7 @@ namespace simmer {
         value(value), mod(mod), op(internal::get_op<double>(mod)) {}
 
     SetQueue(int id, const T& value, char mod='N')
-      : Activity("SetQueue"), internal::ResGetter("SetQueue", "[]", id),
+      : Activity("SetQueue"), internal::ResGetter("SetQueue", id),
         value(value), mod(mod), op(internal::get_op<double>(mod)) {}
 
     void print(unsigned int indent = 0, bool verbose = false, bool brief = false) {

inst/include/simmer/activity/resource_internal.h

@@ -29,16 +29,24 @@ namespace simmer { namespace internal {
   public:
     BASE_CLONEABLE(ResGetter)
 
-    ResGetter(const std::string& activity, const std::string& resource, int id = -1)
-      : resource(resource), id(id), activity(activity) {}
+    ResGetter(const std::string& activity)
+      : resource(MakeString() << "[all]"), id(-2), activity(activity) {}
+
+    ResGetter(const std::string& activity, const std::string& resource)
+      : resource(resource), id(-1), activity(activity) {}
+
+    ResGetter(const std::string& activity, int id)
+      : resource(MakeString() << "[" << id << "]"),
+        id(std::abs(id)), activity(activity) {}
 
   protected:
     std::string resource;
     int id;
 
     Resource* get_resource(Arrival* arrival) const {
       Resource* selected = NULL;
-      if (id < 0)
+      if (id == -2) return selected;
+      if (id == -1)
         selected = arrival->sim->get_resource(resource);
       else selected = arrival->get_resource_selected(id);
       if (!selected) Rcpp::stop("no resource selected");