PDQ User Manual Online

Updated: Apr 29, 2010

Contents

1  Overview

2  The PDQ Library

2.1  Data Types

1. PDQ Node Types

    
   	CEN: Generic queueing center. Used with CreateNode.
   	
   	DLY: Generic delay center. Used with CreateNode.
   	
   

   
   
   
2. 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.
   	
   

   
   
   
3. Workload Streams

    
   	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. 
   

   
   
   
4. Solution Methods

    APPROX: Uses the approximate MVA solution technique. 
   	See chapter 2 for details. Only consistent in the context of solving a closed queueing circuit.
   	An approximation to the EXACT or iterative MVA solution method. Used with Solve.
   
   	CANON: Uses the canonical solution technique. See Chapter 2 (and the online PDQ User Manual) for
   	more details. Only consistent in the context of a open queueing circuit. Used as an argument for
   	the Solve function.
   
   	EXACT: This solution technique uses the iterative MVA (Mean Value Analysis) method for up to
   	three workload classes. Only consistent in the context of a closed queueing circuit. Used as an
   	argument for the Solve function.
   	
   

   
   
   

2.2  Function Libraries

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

2.3  Function Prefixes

PDQ prefix in ANSI C is PDQ_xxxx

PDQ prefix in Perl is pdq::xxxx for functions and $pdq::xxx for PDQ variables

PDQ prefix in Python is pdq.xxxx

PDQ prefix in R is not required 

3  Function Syntax

3.1  CreateClosed

int PDQ_CreateClosed(char *name, int TERM, float users, float think);

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

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

CreateClosed(name, TERM, users, think)

Define the workload for a CLOSED circuit queueing circuit. A separate call to CreateClosed is
required for each workload stream that has different characteristics.

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: Cumulative number of workload streams created.

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

CreateOpen, Init

3.2  CreateMultiNode

int PDQ_CreateMultiNode(int servers, char *name, int device, int sched);

pdq::CreateMultiNode($servers, $name, $pdq::CEN, $pdq::FCFS);

pdq.CreateMultiNode(servers, name, pdq.CEN, pdq.FCFS)

CreateMultiNode(servers, name, CEN, FCFS)

Implemented in release 5.0 of PDQ.

CreateMultiNode is used to define a multiserver queueing node in an open-circuit queueing model,
i.e., an M/M/1 queue. A separate call is required for each instance of a multiserver queueing node.

$n = pdq::CreateMultiNode(4, "cores",  $pdq::CEN, $pdq::FCFS);

CreateNode

3.3  CreateNode

int PDQ_CreateNode(char *name, int device, int sched);

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

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

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: the the cumulative number of queueing nodes created.

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

CreateOpen, Init

3.4  CreateOpen

int PDQ_CreateOpen(char *name, float lambda);

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

pdq.CreateOpen(name, lambda)

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: the cumulative number of open workloads created.

$s = pdq::CreateOpen("IOcmds", 10.0);

CreateClosed, Init

3.5  GetLoadOpt

double PDQ_GetLoadOpt(int class, char *wname);

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

pdq.GetLoadOpt(pdq.CLASS, wname)

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::CLASS, $wname);

GetThruput, GetResponse

3.6  GetQueueLength

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

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

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

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 queue length as a decimal number.

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

GetResidenceTime, GetUtilization

3.7  GetResidenceTime

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

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

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

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 residence time as a decimal number.

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

GetQueueLength, GetUtilization

3.8  GetResponse

double PDQ_GetResponse(int class, char *wname);

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

pdq.GetResponse(pdq.CLASS, wname)

GetResponse(CLASS, wname)

GetResponse used to determine the system response time for the specified workload.

class: TRANS, TERM, or BATCH type.

wname: A string containing the name of the workload.

RETURNS: the system response time as a decimal number.

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

CreateClosed, Init, CreateOpen

3.9  GetThruMax

double PDQ_GetThruMax(int class, char *wname);

pdq::GetThruMax($pdq::CLASS, $wname);

pdq.GetThruMax(pdq.CLASS, wname)

GetThruMax(CLASS, wname)

GetThruMax is used to determine the upper bound on system throughput for the specified workload.

class: TERM, or BATCH type.

wname: A string containing the name of the workload.

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

$Xmax = pdq::GetThruMax($pdq::CLASS, $wname);

GetThruput

3.10  GetThruput

double PDQ_GetThruput(int class, char *wname);

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

pdq.GetThruput(pdq.CLASS, wname)

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 system throughput as a decimal number.

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

GetResponse

3.11  GetUtilization

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

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

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

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 utilization as a decimal fraction in the range 0.0 to 1.0.

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

GetResponse, GetThruput, Solve

3.12  Init

void PDQ_Init(char *modelName);

pdq::Init($modelName);

pdq.Init(modelName)

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.13  Report

void PDQ_Report();

pdq::Report();

pdq.Report()

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.14  SetDebug

void PDQ_SetDebug(int flag);

pdq::SetDebug($flag);

pdq.SetDebug(flag)

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.15  SetDemand

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

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

pdq.SetDemand(nodename, workname, servicetime)

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.16  SetTUnit

void PDQ_SetTUnit(char *unitname);

pdq::SetTUnit($unitname);

pdq.SetTUnit(unitname)

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

RETURNS: None.

pdq::SetTUnit("Hours");

Report

3.17  SetVisits

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

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

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

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.18  SetWUnit

void PDQ_SetWUnit(char *unitname);

pdq::SetWUnit($unitname);

pdq.SetWUnit(unitname)

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.

RETURNS: None.

pdq::SetWUnit("Updates");

Report

3.19  Solve

int PDQ_Solve(int method);

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

pdq.Solve(pdq.method)

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: APPROX or CANON are used in conjunction with CreateOpen. 
        EXACT used in conjunction with CreateClosed.

RETURNS: None.

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

CreateOpen, CreateClosed