PDQ Online User Manual (original) (raw)
PDQ Online User Manual
Updated for PDQ 7.0.0
This online manual provides easy reference to the syntax of PDQ functions in R, Perl, Python, and ANSI C(the native code of the PDQ library). For consistency with the book Analyzing Computer System Performance with Perl::PDQ (2005, 2011) the examples are shown in Perl only. The C function syntax updates the original PDQ functions defined in The Practical Performance Analyst (1998, 2000).
Contents
1 Overview
2 The PDQ Library
2.1 Data Types
2.2 Function Libraries
2.3 Function Prefixes
3 Function Syntax
3.1 CreateClosed
3.2 CreateMultiNode
3.3 CreateNode
3.4 CreateOpen
3.5 GetNodesCount
3.6 GetLoadOpt
3.7 GetQueueLength
3.8 GetResidenceTime
3.9 GetResponse
3.10 GetStreamsCount
3.11 GetThruput
3.12 GetUtilization
3.13 Init
3.14 Report
3.15 SetComment
3.16 SetDebug
3.17 SetDemand
3.18 SetTUnit
3.19 SetVisits
3.20 SetWUnit
3.21 Solve
1 Overview
See the Pretty Damn Quick (PDQ) modeling overviewand the PDQ software installation instructions.
2 The PDQ Library
In this section we describe the global variables, public data types, and public functions defined in the PDQ_Lib.h file contained in the download distribution.
2.1 Data Types
The following data types (implemented as #defines in C) are used in conjunction with PDQ library functions. See the synopses of procedures for actual syntax.
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.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.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.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
To access the PDQ functions use the following statements at the beginning of your modeling code.
C: #include "PDQ_Lib.h" Perl: use pdq; Python: import pdq R: library(pdq)
2.3 Function Prefixes
In most languages, an explicit prefix is required to indicate the relevant library namespace to the compiler or interpreter.
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.
Note that Perl uses a double colon for both functions and variables, but the latter prefix has a prepended dollar sign, e.g., $pdq::var. An alphabetical list of functions is provided in Section 3.
3 Function Syntax
The syntax for each function is presented in the order: C, Perl, Python, R. Example usage is shown using Perl code only.
3.1 CreateClosed
SYNTAX
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, pdq::TERM, pdq::TERM, users, $think);
Python - pdq.CreateClosed(name, pdq.TERM, users, think)
R - pdq::CreateClosed(name, TERM, users, think)
DESCRIPTION
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.
OPTIONS
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.
EXAMPLE
pdq::CreateClosed("DBsessions", $pdq::TERM, 57.4, 31.6);
SEE ALSO
CreateOpen, Init
3.2 CreateMultiNode
SYNTAX
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, name, name, pdq::MSO, $pdq::FCFS); pdq::CreateMultiNode($servers, name, name, 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)
DESCRIPTION
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.
EXAMPLE
pdq::CreateMultiNode(16, "cores", pdq::MSO, pdq::MSO, pdq::MSO, pdq::FCFS);
SEE ALSO
CreateNode
3.3 CreateNode
SYNTAX
ANSI C - int PDQ_CreateNode(char *name, int device, int sched);
Perl - pdq::CreateNode($name, pdq::CEN, pdq::CEN, pdq::CEN, pdq::FCFS);
Python - pdq.CreateNode(name, pdq.CEN, pdq.FCFS)
R - pdq::CreateNode(name, CEN, FCFS)
DESCRIPTION
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.
EXAMPLE
pdq::CreateNode("cpu", pdq::CEN, pdq::CEN, pdq::CEN, pdq::FCFS);
SEE ALSO
CreateOpen, Init
3.4 CreateOpen
SYNTAX
ANSI C - int PDQ_CreateOpen(char *name, float lambda);
Perl - pdq::CreateOpen($name, $lambda);
Python - pdq.CreateOpen(name, lambda)
R - pdq::CreateOpen(name, lambda)
DESCRIPTION
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.
EXAMPLE
pdq::CreateOpen("IOcmds", 10.0);
SEE ALSO
CreateClosed, Init
3.5 GetNodesCount
SYNTAX
ANSI C - int PDQ_GetNodesCount();
Perl - pdq::GetNodesCount();
Python - pdq.GetNodesCount()
R - GetNodesCount()
DESCRIPTION
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
SYNTAX
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)
DESCRIPTION
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.
EXAMPLE
Nopt = pdq::GetLoadOpt(Nopt = pdq::GetLoadOpt(Nopt = pdq::GetLoadOpt(pdq::TERM, $wname);
SEE ALSO
GetThruput, GetResponseTime
3.7 GetQueueLength
SYNTAX
ANSI C - double PDQ_GetQueueLength(char *device, char *work, int class);
Perl - pdq::GetQueueLength($device, work, work, work, pdq::CLASS);
Python - pdq.GetQueueLength(device, work, pdq.CLASS)
R - GetQueueLength(device, work, CLASS)
DESCRIPTION
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.
EXAMPLE
q = pdq::GetQueueLength(q = pdq::GetQueueLength(q = pdq::GetQueueLength(device, work, work, work, pdq::TRANS);
SEE ALSO
GetResidenceTime, GetUtilization
3.8 GetResidenceTime
SYNTAX
ANSI C - double PDQ_GetResidenceTime(char *device, char *work, int class);
Perl - pdq::GetResidenceTime($device, work, work, work, pdq::CLASS);
Python - pdq.GetResidenceTime(device, work, pdq.CLASS);
R - GetResidenceTime(device, work, CLASS)
DESCRIPTION
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.
EXAMPLE
RezT = pdq::GetResidenceTime(RezT = pdq::GetResidenceTime(RezT = pdq::GetResidenceTime(device, work, work, work, pdq::TRANS);
SEE ALSO
GetQueueLength, GetUtilization
3.9 GetResponse
SYNTAX
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)
DESCRIPTION
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.
EXAMPLE
RT = pdq::GetResponse(RT = pdq::GetResponse(RT = pdq::GetResponse(pdq::TERM, $wname);
SEE ALSO
CreateWorkloadClosed, Init, CreateWorkloadOpen, GetResidenceTime
3.10 GetStreamsCount
SYNTAX
ANSI C - int PDQ_GetStreamsCount();
Perl - pdq::GetStreamsCount();
Python - pdq.GetStreamsCount()
R - pdq::GetStreamsCount()
DESCRIPTION
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
SYNTAX
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)
DESCRIPTION
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.
EXAMPLE
X = pdq::GetThruput(X = pdq::GetThruput(X = pdq::GetThruput(pdq::TRANS, $wname);
SEE ALSO
GetResponse
3.12 GetUtilization
SYNTAX
ANSI C - double PDQ_GetUtilization(char *device, char *work, int class);
Perl - pdq::GetUtilization($device, wname, wname, wname, pdq::CLASS);
Python - pdq.GetUtilization(device, wname, pdq.CLASS)
R - pdq::GetUtilization(device, wname, CLASS)
DESCRIPTION
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.
EXAMPLE
U = pdq::GetUtilization(U = pdq::GetUtilization(U = pdq::GetUtilization(device, wname, wname, wname, pdq::TRANS);
SEE ALSO
GetResponse, GetThruput, Solve
3.13 Init
SYNTAX
ANSI C - void PDQ_Init(char *modelName);
Perl - pdq::Init($modelName);
Python - pdq.Init(modelName)
R - pdq::Init(modelName)
DESCRIPTION
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.
EXAMPLE
pdq::Init($modelName);
SEE ALSO
Solve, Report
3.14 Report
SYNTAX
ANSI C - void PDQ_Report();
Perl - pdq::Report();
Python - pdq.Report()
R - pdq::Report()
DESCRIPTION
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.
EXAMPLE
SEE ALSO
Init, Solve
3.15 SetComment
SYNTAX
ANSI C - void PDQ_SetComment("text");
Perl - pdq::SetComment("text");
Python - pdq.SetComment("text")
R - pdq::SetComment("text")
DESCRIPTION
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.
EXAMPLE
pdq::SetComment("This is a comment.")
SEE ALSO
Report
3.16 SetDebug
SYNTAX
ANSI C - void PDQ_SetDebug(int flag);
Perl - pdq::SetDebug($flag);
Python - pdq.SetDebug(flag)
R - pdq::SetDebug(flag)
DESCRIPTION
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.
EXAMPLE
pdq::SetDebug(1)
SEE ALSO
Init
3.17 SetDemand
SYNTAX
ANSI C - void PDQ_SetDemand(char *nodename, char *workname, float servicetime);
Perl - pdq::SetDemand($nodename, workname, workname, workname, servicetime);
Python - pdq.SetDemand(nodename, workname, servicetime)
R - pdq::SetDemand(nodename, workname, servicetime)
DESCRIPTION
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.
EXAMPLE
PDQ_SetDemand("DBserver", "OLTPtx", 0.130);
SEE ALSO
CreateClosed, CreateNode, CreateOpen, SetVisits
3.18 SetTUnit
SYNTAX
ANSI C - void PDQ_SetTUnit(char *unitname);
Perl - pdq::SetTUnit($unitname);
Python - pdq.SetTUnit(unitname)
R - pdq::SetTUnit(unitname)
DESCRIPTION
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.
EXAMPLE
pdq::SetTUnit("Hours");
SEE ALSO
Report
3.19 SetVisits
SYNTAX
ANSI C - void PDQ_SetVisits(char *nodename, char *workname, float visits, float stime);
Perl - pdq::SetVisits($nodename, workname, workname, workname, visits, $stime);
Python - pdq.SetVisits(nodename, workname, visits, stime)
R - pdq::SetVisits(nodename, workname, visits, stime)
DESCRIPTION
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.
EXAMPLE
pdq::SetVisits("cpu", "DBsessions", 10.0, 0.013);
SEE ALSO
CreateClosed, CreateNode, CreateOpen, SetDemand
3.20 SetWUnit
SYNTAX
ANSI C - void PDQ_SetWUnit(char *unitname);
Perl - pdq::SetWUnit($unitname);
Python - pdq.SetWUnit(unitname)
R - pdq::SetWUnit(unitname)
DESCRIPTION
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.
EXAMPLE
pdq::SetWUnit("Updates");
SEE ALSO
Report
3.21 Solve
SYNTAX
ANSI C - int PDQ_Solve(int method);
Perl - pdq::Solve($pdq::method);
Python - pdq.Solve(pdq.method)
R - pdq::Solve(method)
DESCRIPTION
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.
EXAMPLE
pdq::Solve($pdq::APPROX);
SEE ALSO
CreateOpen, CreateClosed
File translated from TEX by TTH, version 3.81.
On 27 Apr 2021, 09:36.