PDQ Online User Manual

Updated for PDQ 7.0.0

Contents

1  Overview

2  The PDQ Library

2.1  Data Types

1. PDQ Workload or Streams Types

    
   	BATCH: A batch class workload which is defined to be one with zero thinktime. Only consistent in
   	the context of a closed queueing circuit to distinguish from TERM. Used with CreateClosed.
   
   	TERM: A terminal class workload which is defined to be one with non-zero thinktime.  Only
   	consistent in the context of a closed queueing circuit to distinguish from BATCH. Used with
   	CreateClosed.
   
   	TRANS: A transaction class workload which is defined by an arrival rate rather than a thinktime.
   	Only consistent in the context of a open queueing circuit. Used with CreateOpen. 
   
2. PDQ Node Types

    
   	CEN: Generic queueing center. Used with CreateNode.
   
   	The following are new in PDQ 7.0.0:
   	MSO: Multi-server queue with open network. Used with CreateMultiNode.
   	MSC: Multi-server queue with closed network. Used with CreateMultiNode.
   	
   
3. Service Disciplines

    
   	FCFS: First-come first-served. Used with CreateNode.
   	ISRV: Infinite server. Used with CreateNode.
   	LCFS: Last-come first-served. Used with CreateNode.
   	PSHR: Processor sharing. Used with CreateNode.
   	
   
4. Solution Methods

    
   	CANON: A possible argument for the PDQ Solve() function.
   	Only consistent with solving an OPEN queueing circuit.
   	Uses the canonical solution technique.
   	
   	EXACT: A possible argument for the PDQ Solve() function.
   	Only consistent with solving a CLOSED queueing circuit. 
   	This solution technique uses the iterative MVA (Mean Value Analysis) method for up to
   	three workload classes. 
   	
   	APPROX: An argument for the PDQ Solve() function.
   	Only consistent with solving a CLOSED queueing circuit. 
   	An approximation to the EXACT or iterative MVA solution method.
   	
   

2.2  Function Libraries

C:       #include "PDQ_Lib.h" 
Perl:    use pdq;
Python:  import pdq
R:       library(pdq)

2.3  Function Prefixes

ANSI C uses an underbar, e.g., PDQ_foo()

Perl uses a double colon, e.g.,  pdq::foo()

Python uses a dot, e.g.,  pdq.foo()

R uses a double colon, e.g.,  pdq::foo(), like Perl, but it is an option unless there is a name conflict.

3  Function Syntax

3.1  CreateClosed

Will be deprecated beyond PDQ 7.0:

ANSI C - void PDQ_CreateClosed(char *name, int TERM, float users, float think);
         void PDQ_CreateClosedWorkload(char *name, int should_be_class, double pop, double think);

Perl   - pdq::CreateClosed($name, $pdq::TERM, $users, $think);

Python - pdq.CreateClosed(name, pdq.TERM, users, think)

R      - pdq::CreateClosed(name, TERM, users, think)

Define the workload for a CLOSED circuit queueing network. A separate call to CreateClosed  or CreateClosedWorkload is
required for each workload stream that is defined.
New in PDQ 7.0, an integer value (stream count) is no longer return by these functions. Use PDQ_GetStreamsCount for that.

name: String used to identify the workload name in reports or debug output.

class: Either TERM or BATCH type

users: The number of active user processes in the closed circuit.
This argument is a float to accommodate  measured activity e.g.,
57.4 average active users

think: User think-time delay before the next request is issued.

RETURNS: None.

pdq::CreateClosed("DBsessions", $pdq::TERM,  57.4, 31.6);   

CreateOpen, Init

3.2  CreateMultiNode

ANSI C - void PDQ_CreateMultiNode(int servers, char *name, MSO, FCFS);
         void PDQ_CreateMultiNode(int servers, char *name, MSC, FCFS);

Perl   - pdq::CreateMultiNode($servers, $name, $pdq::MSO, $pdq::FCFS);
         pdq::CreateMultiNode($servers, $name, $pdq::MSC, $pdq::FCFS);

Python - pdq.CreateMultiNode(servers, name, pdq.MSO, pdq.FCFS)
         pdq.CreateMultiNode(servers, name, pdq.MSC, pdq.FCFS)
         
R      - pdq::CreateMultiNode(servers, name, MSO, FCFS)
         pdq::CreateMultiNode(servers, name, MSC, FCFS)

CreateMultiNode is used to define a multiserver queueing node in either an open (MSO) or closed (MSC) queueing netowrk. 
A multiserver queueing node has a single waiting line (like CreateNode) but that line is serviced by more than one facility or server. 
Different solution techniques are applied depending on whether the funciton argument is specified as MSO (open) or MSC (closed). 
A separate call is required for each instance of a multiserver queueing node.

pdq::CreateMultiNode(16, "cores",  $pdq::MSO, $pdq::FCFS);

CreateNode

3.3  CreateNode

ANSI C - int PDQ_CreateNode(char *name, int device, int sched);

Perl   - pdq::CreateNode($name, $pdq::CEN, $pdq::FCFS);

Python - pdq.CreateNode(name, pdq.CEN, pdq.FCFS)

R      - pdq::CreateNode(name, CEN, FCFS)

Defines a queueing service node for either a closed or open circuit model.  A separate call is
required for each queueing node instance.

name: A string used to identify the service node in reports or
debug logs.

device: Type of device.  Typically CEN.

sched: The queueing discipline.  Most commonly FCFS.

RETURNS: None.

pdq::CreateNode("cpu",  $pdq::CEN, $pdq::FCFS);

CreateOpen, Init

3.4  CreateOpen

ANSI C - int PDQ_CreateOpen(char *name, float lambda);

Perl   - pdq::CreateOpen($name, $lambda);

Python - pdq.CreateOpen(name, lambda)

R      - pdq::CreateOpen(name, lambda)

Define a workload in an open circuit queueing model.  A separate call is required for workload
streams having different characteristics.

name: A string used to identify the workload in reports or debug
logs.

lambda: The arrival rate per unit time into the queueing circuit.

RETURNS: None.

pdq::CreateOpen("IOcmds", 10.0);

CreateClosed, Init

3.5  GetNodesCount

ANSI C - int PDQ_GetNodesCount();

Perl   - pdq::GetNodesCount();

Python - pdq.GetNodesCount()

R      - GetNodesCount()

GetNodesCount is used to determine the total number of PDQ nodes (i.e., queueing centers) 
that have been defined by calling CreateNode and/or CreateMultiNode.

RETURNS: the number of nodes created.

3.6  GetLoadOpt

ANSI C - double PDQ_GetLoadOpt(int class, char *wname);

Perl   - pdq::GetLoadOpt($pdq::CLASS, $wname);

Python - pdq.GetLoadOpt(pdq.CLASS, wname)

R      - pdq::GetLoadOpt(CLASS, wname)

GetLoadOpt is used to determine the optimal number of users for the
specified workload.

class: TERM, or BATCH type.

wname: A string containing the name of the workload.

RETURNS: returns the optimal user load as a real number.

$Nopt = pdq::GetLoadOpt($pdq::TERM, $wname);

GetThruput, GetResponseTime

3.7  GetQueueLength

ANSI C - double PDQ_GetQueueLength(char *device, char *work, int class);

Perl   - pdq::GetQueueLength($device, $work, $pdq::CLASS);

Python - pdq.GetQueueLength(device, work, pdq.CLASS)

R      - GetQueueLength(device, work, CLASS)

GetQueueLength is used to determine the queue length of the designated service node by the specified
workload.  It should only be called after the PDQ model has been solved.

device: A string containing the name of the queueing service node.

work: A string containing the name of the workload.

class: TRANS, TERM, or BATCH type.

RETURNS: returns the mean queue length as a decimal number.

$q = pdq::GetQueueLength($device, $work, $pdq::TRANS);

GetResidenceTime, GetUtilization

3.8  GetResidenceTime

ANSI C - double PDQ_GetResidenceTime(char *device, char *work, int class);

Perl   - pdq::GetResidenceTime($device, $work, $pdq::CLASS);

Python - pdq.GetResidenceTime(device, work, pdq.CLASS);

R      - GetResidenceTime(device, work, CLASS)

GetResidenceTime is used to determine the residence time at the designated service node due the
specified workload.  It should only be called after the PDQ model has been solved.

device: A string containing the name of the queueing service node.

work: A string containing the name of the workload.

class: TRANS, TERM, or BATCH type.

RETURNS: returns the mean residence time as a decimal number.

$RezT = pdq::GetResidenceTime($device, $work, $pdq::TRANS);

GetQueueLength, GetUtilization

3.9  GetResponse

ANSI C - double PDQ_GetResponse(int class, char *wname);

Perl   - pdq::GetResponse($pdq::CLASS, $wname);

Python - pdq.GetResponse(pdq.CLASS, wname)

R      - pdq::GetResponse(CLASS, wname)

GetResponse is used to determine the system response time for the specified workload.
For a single queueing node, GetResponse returns the same result as GetResidenceTime.
Note that this is the time (R) in the queueing system and does not include think time (Z).
Adding the think time to the GetResponse value gives the total round-trip time R + Z.

class: TRANS, TERM, or BATCH type.

wname: A string containing the name of the workload.

RETURNS: the mean system response time as a decimal number.

$RT = pdq::GetResponse($pdq::TERM, $wname);

CreateWorkloadClosed, Init, CreateWorkloadOpen, GetResidenceTime

3.10  GetStreamsCount

ANSI C - int PDQ_GetStreamsCount();

Perl   - pdq::GetStreamsCount();

Python - pdq.GetStreamsCount()

R      - pdq::GetStreamsCount()

GetStreamsCount is used to determine the total number of PDQ streams (i.e., workloads or workflows) 
that have been defined by calling CreateOpen or CreateClosed.

RETURNS: the number of streams created.

3.11  GetThruput

ANSI C - double PDQ_GetThruput(int class, char *wname);

Perl   - pdq::GetThruput($pdq::CLASS, $wname);

Python - pdq.GetThruput(pdq.CLASS, wname)

R      - pdq::GetThruput(CLASS, wname)

GetThruput is used to determine the system throughput for the
specified workload.

class: TRANS, TERM, or BATCH type.

wname: A string containing the name of the workload.

RETURNS: returns the mean system throughput as a decimal number.

$X = pdq::GetThruput($pdq::TRANS, $wname);

GetResponse

3.12  GetUtilization

ANSI C - double PDQ_GetUtilization(char *device, char *work, int class);

Perl   - pdq::GetUtilization($device, $wname, $pdq::CLASS);

Python - pdq.GetUtilization(device, wname, pdq.CLASS)

R      - pdq::GetUtilization(device, wname, CLASS)

GetUtilization is used to determine the utilization of the designated service node by the specified
workload.  It should only be called after the PDQ model has been solved.

device: A string containing the name of the queueing service node.

work: A string containing the name of the workload.

class: TRANS, TERM, or BATCH type.

RETURNS: returns the mean utilization as a decimal fraction in the range 0.0 to 1.0.

$U = pdq::GetUtilization($device, $wname, $pdq::TRANS);

GetResponse, GetThruput, Solve

3.13  Init

ANSI C - void PDQ_Init(char *modelName);

Perl   - pdq::Init($modelName);

Python - pdq.Init(modelName)

R      - pdq::Init(modelName)

Initializes all internal PDQ variables.  Must be called prior to any other PDQ function. It also
resets all internal PDQ variables so that no separate cleanup function call required.  Init can be
called an arbitrary number of times in the same model.

modelName is a string containing the name of the performance model that will appear in the PDQ
report banner.  To maintain cosmetic appearances in the Report header, the model name should not
exceed 24 characters (including spaces).

RETURNS: None.

pdq::Init($modelName);

Solve, Report

3.14  Report

ANSI C - void PDQ_Report();

Perl   - pdq::Report();

Python - pdq.Report()

R      - pdq::Report()

Report generates a formatted report that includes the total number of nodes and workloads created in
the model, system level performance measures such as throughput and response time for each workload,
and service node performance measures such as node utilization and queue lengths. A comment field is
available to audit input parameter variations across multiple runs of the same model.  To add
comments to a report, simply create or modify a file named comments.pdq. Sample reports produced by
PDQ Reporter appear throughput this book.

RETURNS: None.

Init, Solve

3.15  SetComment

ANSI C - void PDQ_SetComment("text");

Perl   - pdq::SetComment("text");

Python - pdq.SetComment("text")

R      - pdq::SetComment("text")

Include text containing comments and intentions about the PDQ model.

RETURNS: None.  The comment text is included at the beginning of the PDQ Report output.

pdq::SetComment("This is a comment.")

Report

3.16  SetDebug

ANSI C - void PDQ_SetDebug(int flag);

Perl   - pdq::SetDebug($flag);

Python - pdq.SetDebug(flag)

R      - pdq::SetDebug(flag)

Enables diagnostic printout of internal variables and procedures used in solving a PDQ model.

flag is set either TRUE or FALSE to toggle the debug facility.

RETURNS: None.  Output is written to file e.g., debug.log.

pdq::SetDebug(1)

Init

3.17  SetDemand

ANSI C - void PDQ_SetDemand(char *nodename, char *workname, float servicetime);

Perl   - pdq::SetDemand($nodename, $workname, $servicetime);

Python - pdq.SetDemand(nodename, workname, servicetime)

R      - pdq::SetDemand(nodename, workname, servicetime)

Define the service demand of a specific workload.  The named node and workload must have been
defined previously. A separate call is required for each workload stream that accesses the same
node.

nodename: the string name of the queueing node.

workname: the string name of the workload.

time: service demand (in units of time) required by the workload at that node.

RETURNS: None.

PDQ_SetDemand("DBserver", "OLTPtx", 0.130);

CreateClosed, CreateNode, CreateOpen, SetVisits

3.18  SetTUnit

ANSI C - void PDQ_SetTUnit(char *unitname);

Perl   - pdq::SetTUnit($unitname);

Python - pdq.SetTUnit(unitname)

R      - pdq::SetTUnit(unitname)

Change the name of the time unit that appears in the PDQ report. The default time unit is Seconds.

unitname: a string name of the unit.

Must call CreateOpen or CreateClosed prior to using.


RETURNS: None.

pdq::SetTUnit("Hours");

Report

3.19  SetVisits

ANSI C - void PDQ_SetVisits(char *nodename, char *workname, float visits, float stime);

Perl   - pdq::SetVisits($nodename, $workname, $visits, $stime);

Python - pdq.SetVisits(nodename, workname, visits, stime)

R      - pdq::SetVisits(nodename, workname, visits, stime)

Used to define the service demand of a specific workload in terms of the explicit service time and
visit count.  The named node and workload must exist. A separate call is required for each workload
stream that accesses the same node.  SetVisits is different from PDQ_SetDemand in the way node-level
performance metrics are formatted in the Report output. The number of visits shows up in the Report
INPUTS section. The throughput in the RESOURCE Performance section shows up as counts per unit time.

nodename: name of the queueing node.

workname: name of the workload.

visits: number of visits to that node. Dimensionless.

stime: service time the workload requires at that node (in time
units).

RETURNS: None.

pdq::SetVisits("cpu", "DBsessions", 10.0, 0.013);

CreateClosed, CreateNode, CreateOpen, SetDemand

3.20  SetWUnit

ANSI C - void PDQ_SetWUnit(char *unitname);

Perl   - pdq::SetWUnit($unitname);

Python - pdq.SetWUnit(unitname)

R      - pdq::SetWUnit(unitname)

PDQ_SetWUnit changes the name of the work unit that appears in the
PDQ report. The default work unit is Job.

unitname: The name of the work unit.

Must call CreateOpen or CreateClosed prior to using.

RETURNS: None.

pdq::SetWUnit("Updates");

Report

3.21  Solve

ANSI C - int PDQ_Solve(int method);

Perl   - pdq::Solve($pdq::method);

Python - pdq.Solve(pdq.method)

R      - pdq::Solve(method)

Solve is called after the PDQ model has been created.   An appropriate solution method must be
passed as an argument or an error will reported at runtime.

method: CANON are used in conjunction with CreateOpen. 
        EXACT (limited to 1000 users) or APPROX (unlimited users) are used in conjunction with CreateClosed.

RETURNS: None.

pdq::Solve($pdq::APPROX);

CreateOpen, CreateClosed