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:

  • busy() - tell the scheduler how much time the current

    operation takes

  • wait() - wait for an event: Event can be a timeout,

    a simulation timer expiration, or a message arriving on an input port

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

    vThreads can wait() for messages. They can read messages from the input ports via

    • read_msg() - read one message from port

    • n_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
  • ptype (str) –

    must be one of

    • ’SamplingIn’,

    • ’QueuingIn’,

    • ’SamplingIO’

    • ’QueuingIO’

    • ’in’

    • ’out’

    • ’io’

  • list_port_names (list) – list of port names to create

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

new_vt_timer(name)[source]

Add a new virtual timer to the part

Parameters

name – name of timer

run_vthread()[source]

Model code of the VThread. can be overridden by subclass

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, or VtTimer 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 or VtIOPort.

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
Returns

‘ok’ if one of the events has been triggered, ‘timeout’ if timeout

Raises

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

  • wakes up the vThread from wait() if the vThread is waiting for input on that port

  • provides an API to read the messages from the buffer

n_msg()[source]

Check how many messages are in the port’s buffer. Overwritten by subclass

read_msg(default=None)[source]

Read a message from the port’s buffer. Overwritten by subclass

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

n_msg()[source]
Returns

1 if message is available, or 0 if not

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

n_msg()[source]
Returns

number of messages in queue

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 or VtQueuingInPort

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 with start() and restart()

Parameters
  • sim – Simulator instance

  • name – timer name

  • vThread (vThread) – vThread to which the timer shall be added to

has_fired()[source]
Returns

True if timer expired

restart(timeout)[source]

Restart timer, works whether timer is running or not.

Parameters

timeout – Timer will fire after timeout

start(timeout)[source]

Start the timer.

Parameters

timeout – Timer will fire after timeout

Raise

RuntimeError if timer already started

Raise

AttributeError if timeout <= 0

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.

class moddy.vt_sched_rtos.VSimpleProg(sim, **v_thread_args)[source]

A special version of a VThread that has its own scheduler and no concurrency

Parameters
  • sim – Simulator instance

  • v_thread_args – see VThread for parameters