Class ::xotcl::THREAD

::xotcl::THREAD[i] create ... \
           [ -exithandler (default "ns_log notice "EXITHANDLER of slave thread SELF [pid]"") ] \
           [ -lightweight (default "0") ] \
           [ -persistent (default "0") ]

Defined in

Class Relations

  • class: ::xotcl::Class[i]
  • superclass: ::xotcl::Object[i]
::xotcl::Class create ::xotcl::THREAD \
     -superclass ::xotcl::Object

Methods (to be applied on the object)

  • recreate (scripted, private)

     xotcl::THREAD[i] recreate obj args [ args... ]

    this method catches recreation of THREADs in worker threads it reinitializes the thread according to the new definition.

    Parameters:
    obj (required)
    args (required)

    Testcases:
    No testcase defined.
    :log "recreating [self] $obj, tid [$obj exists tid]"
    if {![string match "::*" $obj]} { set obj ::$obj }
    $obj set recreate 1
    next
    $obj init [lindex $args 0]
    if {[nsv_exists [self] $obj] && [$obj exists initcmd]} {
      set tid [nsv_get [self] $obj]
      ::thread::send $tid [$obj set initcmd]
      $obj set tid $tid
      :log "+++ content of thread $obj ($tid) redefined"
    }
  • shutdown (scripted, private)

     xotcl::THREAD[i] shutdown registry obj tid

    Compatibility entry point for already registered shutdown callbacks.

    Parameters:
    registry (required)
    shared thread registry
    obj (required)
    thread controller name
    tid (required)
    registered worker identifier

    Testcases:
    No testcase defined.
    ::xo::thread_shutdown $registry $obj $tid

Methods (to be applied on instances)

  • check_blueprint (scripted)

    if {![[self class] exists __blueprint_checked]} {
      if {[string first ::xotcl::THREAD [ns_ictl get]] == -1} {
        _ns_savenamespaces
      }
      [self class] set __blueprint_checked 1
    }
  • destroy (scripted, public)

     <instance of xotcl::THREAD[i]> destroy

    Destroy the thread controller and release its worker if it is nonpersistent. Persistent workers are managed by the shutdown callback.

    Testcases:
    thread_destroy_after_cache_cleanup
    :log "destroy called"
    if {!${:persistent} &&
        [nsv_exists [self class] [self]]} {
      set tid [nsv_get [self class] [self]]
      set refcount [::thread::release $tid]
      :log "destroying thread object tid=$tid cnt=$refcount"
      if {$refcount == 0} {
        :log "thread terminated"
        nsv_unset [self class] [self]
        ns_mutex destroy ${:mutex}
        ns_log notice "mutex ${:mutex} destroyed"
      }
    }
    next
  • do (scripted)

    # A process-wide shutdown request starts connection draining. Existing
    # services must remain usable until their own shutdown callback begins.
    if {[nsv_exists [self class]::stopping [self]]} {
      return -code error -errorcode {XOTCL THREAD SHUTDOWN} "thread [self] is shutting down"
    }
    if {![nsv_exists [self class] [self]]} {
      # The initializer can call its own controller while the creator is
      # waiting for it under the mutex. Dispatch without taking that mutex.
      if {[info exists ::xotcl::currentThread] && $::xotcl::currentThread eq [self]} {
        set tid [::thread::id]
        if {$async} {
          return [::thread::send -async $tid $args]
        }
        return [::thread::send $tid $args]
      }
      # lazy creation of a new slave thread
    
      ad_mutex_eval ${:mutex} {
        #:check_blueprint
        #:log "after lock"
        if {![nsv_exists [self class] [self]]} {
          if {[ns_info shutdownpending]} {
            return -code error -errorcode {XOTCL THREAD SHUTDOWN} "cannot start thread [self] during shutdown"
          }
          if {${:lightweight}} {
            :log "CREATE lightweight thread"
            set tid [::thread::create -thin]
          } else {
            set tid [::thread::create]
          }
          if {${:persistent}} {
            :log "--created new persistent [self class] as $tid pid=[pid]"
          } else {
            :log "--created new [self class] as $tid pid=[pid]"
          }
          try {
            if {!${:lightweight} && ![ns_ictl epoch]} {
              # During startup the worker needs the XOTcl blueprint.
              _ns_savenamespaces
              set initcmd [ns_ictl get]
            }
            append initcmd ${:initcmd}
            ::thread::send $tid $initcmd
          } on error {message options} {
            # Keep the registry empty so the next caller can retry.
            catch {::thread::release $tid}
            return -options $options $message
          }
    
          # Publish only after the worker has finished initializing.
          nsv_set [self class] [self] $tid
          if {${:persistent}} {
            ns_atshutdown ::xo::thread_shutdown [self class] [self] $tid
          }
        } else {
          set tid [nsv_get [self class] [self]]
        }
      }
    } else {
      #
      # Target thread is already up and running.
      #
      set tid [nsv_get [self class] [self]]
    }
    if {![info exists :tid]} {
      #
      # This is the first call.
      #
      if {!${:persistent} && ![info exists :recreate]} {
        #
        # For a shared thread, we do ref-counting through preserve.
        #
        set tid [nsv_get [self class] [self]]
        :log "THREAD::PRESERVE must preserve for sharing request-thread [pid] tid $tid"
        ::thread::preserve $tid
      }
      set :tid $tid
    }
    if {$async} {
      return [thread::send -async $tid $args]
    } else {
      return [thread::send $tid $args]
    }
  • exithandler (setter)

  • get_tid (scripted)

    if {[nsv_exists [self class] [self]]} {
      # the thread was already started
      return [nsv_get [self class] [self]]
    }
    # The initializer can ask for its own ID before publication.
    if {[info exists ::xotcl::currentThread] && $::xotcl::currentThread eq [self]} {
      return [::thread::id]
    }
    # start a small command in the thread
    :do info exists x
    # now we have the thread and can return the tid
    return ${:tid}
  • init (scripted)

    if {$cmd eq "-noinit"} {return}
    #ns_log notice "+++ THREAD cmd='$cmd', epoch=[ns_ictl epoch]"
    if {![ns_ictl epoch]} {
      #ns_log notice "--THREAD init [self] no epoch"
    
      # We are during initialization. For some unknown reasons, XOTcl
      # is not available in newly created threads, so we have to care for it.
      # We need only a partial initialization, to allow the exit handler
      # to be defined.
      set :initcmd {
        package req XOTcl
        namespace import -force ::xotcl::*
      }
    }
    append :initcmd {
      ns_thread name SELF
    }
    append :initcmd [subst {
      ::xotcl::Object setExitHandler [list [:exithandler]]
    }]
    regsub -all SELF ${:initcmd} [self] :initcmd
    append :initcmd \n [list set ::xotcl::currentScript [info script]] \n [list set ::xotcl::currentThread [self]] \n $cmd
    set :mutex [ns_mutex create ns_mutex[self]]
    ns_log notice "mutex ${:mutex} created"
    next
  • lightweight (setter)

  • persistent (setter)