---

Class Relations

• class: ::nx::EnsembleObject

::nx::EnsembleObject create ::ns::stats::Sampler::slot::__sampling

Methods (to be applied on the object)

• start (scripted)

  #   Start the process-wide sampling callback at the requested interval
  #   in seconds (default 10, range 1..3600). Time units and fractional
  #   seconds are normalized with ns_baseunit. Repeated calls with the
  #   same running interval reuse the scheduler; a different interval
  #   requires stopping the sampler first.
  #
  #   Clears the previous sample and baseline when starting a stopped
  #   sampler. Returns the resulting status dictionary. Persistence
  #   must be enabled separately.
  
  set interval [ns_baseunit -time $interval]
  if {$interval < 1 || $interval > 3600} {
      error "interval must be 1..3600 seconds"
  }
  :locked {
      set state [nsv_get ns_stats control]
      if {[dict get $state running]} {
          if {[dict get $state interval]!=$interval} {
              error "sampler already running with a different interval; stop it before reconfiguring"
          }
      } else {
          dict incr state generation
          dict set state running true
          dict set state interval $interval
          dict set state busy false
          dict set state scheduler [ns_schedule_proc -thread $interval [self] sampling tick]
          nsv_set ns_stats pair {}
          nsv_set ns_stats control $state
      }
  }
  return [:sampling status]

• status (scripted)

  #
  #   Return the process-wide sampler configuration and status, including
  #   running state, scheduler identifier, interval, process instance,
  #   collection errors and readiness of the latest interval sample.
  #
  #   latestAt is in epoch seconds; ageSeconds is the elapsed time since
  #   the latest publication. Both are empty before the first sample.
  #   Does not collect new observations or modify sampler state.
  
  set result [nsv_get ns_stats control]
  dict unset result busy
  dict unset result generation
  set sample [nsv_get ns_stats pair]
  dict set result ready [expr {$sample ne "" && [dict get $sample sampling ready]}]
  dict set result latestAt {}
  dict set result ageSeconds {}
  if {$sample ne ""} {
      set stamp [dict get $sample timestamp]
      dict set result latestAt [expr {$stamp/1000000.0}]
      dict set result ageSeconds [expr {max(0,([clock microseconds]-$stamp)/1000000.0)}]
  }
  return $result

• stop (scripted)

  #
  #   Unschedule collection and invalidate any collection already in
  #   progress so it cannot publish into the stopped sampler.
  #
  #   Retains the latest published sample for subsequent reads.
  #   Returns the resulting status dictionary. Does not disable the
  #   separately configured history persistence callback.
  #
  :locked {
      set state [nsv_get ns_stats control]
      if {[dict get $state running]} {
          ns_unschedule_proc [dict get $state scheduler]
      }
      dict set state running false
      dict incr state generation
      dict set state busy false
      dict set state scheduler {}
      nsv_set ns_stats control $state
  }
  return [:sampling status]

• tick (scripted)

  #
  #   Perform one scheduled collection and publish its interval sample.
  #   Skip collection when the sampler is stopped or another collection
  #   is in progress. Collect observations outside the coordination lock,
  #   then calculate and publish only if the sampler generation is still
  #   current.
  #
  #   Retain the raw snapshot as the next interval baseline. Collection
  #   failures retain the previous publication, update error status and
  #   emit a warning. Does not write SQLite history; persistence runs
  #   through a separate callback.
  #
  set generation {}
  :locked {
      set state [nsv_get ns_stats control]
      if {![dict get $state running] || [dict get $state busy]} {
          return
      }
      set generation [dict get $state generation]
      dict set state busy true
      nsv_set ns_stats control $state
  }
  if {$generation eq ""} {
      return
  }
  try {
      set current [:snapshot]
      :locked {
          set state [nsv_get ns_stats control]
          if {$generation!=[dict get $state generation]} {
              return
          }
          set pair [nsv_get ns_stats pair]
          set previous [expr {$pair eq "" ? "" : [dict get $pair raw]}]
          set sample [:calculate $current $previous [dict get $state interval] [dict get $state instance]]
          dict set sample raw $current
          nsv_set ns_stats pair $sample
          dict set state busy false
          dict set state lastError {}
          nsv_set ns_stats control $state
      }
  } on error {message options} {
      :locked {
          set state [nsv_get ns_stats control]
          if {$generation == [dict get $state generation]} {
              dict set state busy false
              dict incr state errors
              dict set state lastError $message
              nsv_set ns_stats control $state
          }
      }
      ns_log warning "ns_stats: sampling failed: $message"
  }

---