Virtual Thread Reference¶
Virtual Threads allow Moddy users to model sequential programs.
Virtual Thread Class¶
-
class
moddy.vthread.
VThread
(sim, obj_name, parent_obj=None, remote_controlled=False, target=None, elems=None)[source]¶ A virtual thread simulating a software running on an operating system. The scheduler of the operating system schedules the Vthreads.
The simulated software must be written in python and must only call the functions from the scheduler for timing functions:
A Vthread is a
simPart
part, which can exchange messages with other simulation parts, but unlike pure simPart parts,the input ports are
VtInPort
that buffer incoming messages- a sampling input port (
VtSamplingInPort
) buffers always the latest message
- a sampling input port (
a queuing input port (
VtQueuingInPort
) buffers all messages
vThreads can
wait()
for messages. They can read messages from the input ports viaread_msg()
- read one message from portn_msg()
- determine how many messages are pending
- the simPart timers are indirectly available to vThreads via vtTimers
(set a flag on timeout)
- Parameters
sim – Simulator instance
obj_name – part’s name
parent_obj – parent part. None if part has no parent.
remote_controlled (bool) – if True, allow thread state to be controlled through a moddy port “_thread_control_port”. Those threads are not started automatically, but only via explicit “start” message to the “_thread_control_port”. Those threads can be killed via “kill” and restarted via “start”.
_target – Instead of sublcassing vThread and implementing the model code in the subclasses
run_vthread
method, specify the method with your model code in _target. I gets called without parameters.elems (dict) – A dictionary with elements (ports and timers) to create, e.g.
{ 'QueuingIn': 'inPort1', 'out': ['outPort1', 'outPort2'], 'vtTmr' : 'timer1' }
-
exception
TerminateException
[source]¶ Exception that is raised to tell the thread that it shall be terminated because simulator terminates
-
busy
(time, status, status_appearance={})[source]¶ tell the scheduler how much time the current operation takes
- Parameters
time – the busy time. May be 0
status – the status text shown on the sequence diagram life line
status_appearance – defines the decoration of the status box in the sequence diagram. See svgSeqD.statusBox
- Returns
always ‘ok’
- Raises
TerminateException – if simulator stopped
-
create_ports
(ptype, list_port_names)[source]¶ Convinience functions to create multiple vtPorts at once.
- Parameters
The function creates for each port a member variable with this name in the part.
-
create_vt_timers
(list_timer_names)[source]¶ Convinience functions to create multiple vtTimers at once.
- Parameters
list_timer_names – list of timers to create
The function creates for each port a member variable with this name in the part.
-
new_vt_queuing_in_port
(name)[source]¶ Add a new queueing input port (
VtQueuingInPort
) to the part- Parameters
name – name of port
-
new_vt_queuing_io_port
(name)[source]¶ Add a new queueing I/O port(via
VtIOPort
) to the part- Parameters
name – name of port
-
new_vt_sampling_in_port
(name)[source]¶ Add a new sampling input port (
VtSamplingInPort
) to the part- Parameters
name – name of port
-
new_vt_sampling_io_port
(name)[source]¶ Add a new sampling I/O port (via
VtIOPort
) to the part- Parameters
name – name of port
-
wait
(timeout, ev_list=[])[source]¶ Suspend vThread until one of the events in ev_list occurs or timeout
- Parameters
timeout – time to wait for events. If None, wait forever. A timeout value of 0 is invalid.
ev_list (list) – list of events to wait for. Events can be
VtSamplingInPort
,VtQueuingInPort
,VtIOPort
, orVtTimer
object. If ev_list is empty (or omitted), wait for timeout unconditionally.
- Returns
‘ok’ if one of the events has been triggered (it does not tell you which one), ‘timeout’ if timeout
- Raises
TerminateException – if simulator stopped
-
wait_for_monitor
(timeout, monitor_func)[source]¶ Suspend vThread until the ‘monitor_func’ detects a match.
Usefull for stimulation threads to wait until the model has reached some state. The ‘monitor_func’ is called from the simulator at each simulation step. If the ‘monitor_func’ returns True, this function returns to caller.
- Parameters
timeout – time to wait for monitor. If None, wait forever. A timeout value of 0 is invalid.
monitor_func – the monitor function to be triggered at each simulation step. called without parameters
- Returns
‘ok’ the monitor has returned True, ‘timeout’ if timeout
- Raises
TerminateException – if simulator stopped
-
wait_for_msg
(timeout, ports)[source]¶ Suspend vThread until a message is available on at least at one of the ports.
In contrast to
wait()
, you don’t need to check that all ports are empty before calling this method.Note
It makes not a lot of sense to call this method on
VtSamplingInPort
, because once such a port has received at least once a message, this method returns immediately.- Parameters
timeout – time to wait for messsages. If None, wait forever. If 0 is specified, don’t wait, just return what is available.
ports – a port or a list of ports to wait for. Each port can be
VtQueuingInPort
orVtIOPort
.
- Returns
One of the following:
- if multiple ports were specified: tuple (msg, port)
for the first message that is available one of the ports,
- if a single port was specified: msg for the first message
that is available on the ports,
None if no message available
- Raises
TerminateException – if simulator stopped
-
wait_until
(time, ev_list=[])[source]¶ Suspend vThread until one of the events in ev_list occurs or until specified time
- Parameters
time – _target time. Must be >= current simulation time, otherwise
ValueError
is thrownev_list (list) – list of events to wait for. Events can be
VtSamplingInPort
,VtQueuingInPort
, orVtTimer
object
- Returns
‘ok’ if one of the events has been triggered, ‘timeout’ if timeout
- Raises
TerminateException – if simulator stopped
ValueError – if _target time already gone
Ports for Virtual Threads¶
-
class
moddy.vthread.
VtInPort
(sim, name, v_thread, q_depth)[source]¶ Base class for input ports of vThreads which extends the standard input port:
buffers the incoming message: VtInport can be a sampling or queuing port
a
VtSamplingInPort
buffers only the last received messagea
VtQueuingInPort
buffers all messages
wakes up the vThread from
wait()
if the vThread is waiting for input on that portprovides an API to read the messages from the buffer
-
class
moddy.vthread.
VtSamplingInPort
(sim, name, v_thread)[source]¶ Sampling input port for vThreads A sampling port buffers only the last received message A read from the sampling buffer does not consume the buffered message
- Parameters
sim – Simulator instance
name – port name
vThread (vThread) – vThread to which the port shall be added to
-
read_msg
(default=None)[source]¶ Get current message from sampling buffer. The message is not consumed, i.e. if read_msg is called again before a new message comes in, the same message is returned.
- Parameters
default – value to return if no message was received at all
- Raises
BufferError – if no message was received at all AND default is None
- Returns
message in buffer
-
class
moddy.vthread.
VtQueuingInPort
(sim, name, v_thread)[source]¶ Queuing input port for vThreads. A queuing port buffers all messages in a fifo queue. The queue depth is infinite. A read from the buffer consumes the oldest message.
- Parameters
sim – Simulator instance
name – port name
vThread (vThread) – vThread to which the port shall be added to
-
read_msg
(default=None)[source]¶ Get first message from queue. The message is consumed.
- Parameters
default – ignored
- Raises
BufferError – if no message in buffer
- Returns
message in buffer
-
class
moddy.vthread.
VtIOPort
(sim, name, v_thread, in_port)[source]¶ An IOPort that combines a Sampling/Queuing input port and a standard output port
- Parameters
sim – Simulator instance
name – port name
vThread (vThread) – vThread to which the port shall be added to
inPort – The input port for the IO-Port. Either
VtSamplingInPort
orVtQueuingInPort
Timer for Virtual Threads¶
-
class
moddy.vthread.
VtTimer
(sim, name, v_thread)[source]¶ A timer for vThreads which extends the standard simulation timer
When the timer expires, it sets a flag, that the user can test with
has_fired()
. The flag is reset withstart()
andrestart()
- Parameters
sim – Simulator instance
name – timer name
vThread (vThread) – vThread to which the timer shall be added to
RTOS Scheduler Simulation for Virtual Threads¶
-
class
moddy.vt_sched_rtos.
VtSchedRtos
(sim, obj_name, parent_obj)[source]¶ RTOS scheduler for vThreads, an instance of a
SimPart
Behaves as a typical, simple RTOS.
16 thread priorities - 0 is highest priority.
priority based scheduling. Low prio threads run only if no higher thread ready.
Threads with same priority will be scheduled round robin (when one of the same prio threads releases the processor, the next same prio thread which is ready is selected)
- Parameters
sim – Simulator instance
obj_name – scheduler name
parent_obj – parent part. None if scheduler has no parent.
-
add_vthread
(v_thread, prio)[source]¶ - Parameters
v_thread – thread to be added
prio – priority of the thread 0..15 (0=highest)
Checks
v_thread.remoteControl
: if True, allow thread state to be controlled through a moddy port threadControlPort. Those threads are not started automatically, but only via explicit “start” message to the threadControlPort. Those threads can be killed via “kill” and restarted via “start” message.