PDQ Online User Manual

PDQ Online User Manual

Updated: Oct 21, 2013

This abbreviated version of the PDQ User Manual is intended mostly for easy reference to the syntax of PDQ functions in Perl, Python, ANSI C (the native code of the PDQ library) and the R programming language. To maintain consistency with the following books, example usage is presented in Perl only:
  1. The Perl examples accompany Chapter 6 in the 1st edition of Analyzing Computer System Performance with Perl::PDQ (2005).

  2. The Perl examples accompany Appendix D in the 2nd edition of Analyzing Computer System Performance with Perl::PDQ (2011).

NOTE: The C function syntax is an update to 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  GetLoadOpt
    3.6  GetQueueLength
    3.7  GetResidenceTime
    3.8  GetResponse
    3.9  GetThruMax
    3.10  GetThruput
    3.11  GetUtilization
    3.12  Init
    3.13  Report
    3.14  SetComment
    3.15  SetDebug
    3.16  SetDemand
    3.17  SetTUnit
    3.18  SetVisits
    3.19  SetWUnit
    3.20  Solve

1  Overview

See the PDQ: Pretty Damn Quick page and 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.
  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
     
    	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: A possible 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
ANSI C - int PDQ_CreateClosed(char *name, int TERM, float users, float think);

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

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

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

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

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 - int PDQ_CreateMultiNode(int servers, char *name, int device, int sched);

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

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

R      - CreateMultiNode(servers, name, CEN, FCFS)

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

EXAMPLE
pdq::CreateMultiNode(16, "cores",  $pdq::CEN, $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::FCFS);

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

R      - 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::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      - 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  GetLoadOpt

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

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

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

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

SEE ALSO
GetThruput, GetResponse

3.6  GetQueueLength

SYNTAX
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)

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($device, $work, $pdq::CLASS);

SEE ALSO
GetResidenceTime, GetUtilization

3.7  GetResidenceTime

SYNTAX
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)

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($device, $work, $pdq::CLASS);

SEE ALSO
GetQueueLength, GetUtilization

3.8  GetResponse

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

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

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

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

SEE ALSO
CreateClosed, Init, CreateOpen, GetResidenceTime

3.9  GetThruMax

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

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

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

R      - GetThruMax(CLASS, wname)

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

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

SEE ALSO
GetThruput

3.10  GetThruput

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

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

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

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

SEE ALSO
GetResponse

3.11  GetUtilization

SYNTAX
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      - 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($device, $wname, $pdq::CLASS);

SEE ALSO
GetResponse, GetThruput, Solve

3.12  Init

SYNTAX
ANSI C - void PDQ_Init(char *modelName);

Perl   - pdq::Init($modelName);

Python - pdq.Init(modelName)

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

SYNTAX
ANSI C - void PDQ_Report();

Perl   - pdq::Report();

Python - pdq.Report()

R      - 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.14  SetComment

SYNTAX
ANSI C - void PDQ_SetComment("text");

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

Python - pdq.SetComment("text")

R      - 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.15  SetDebug

SYNTAX
ANSI C - void PDQ_SetDebug(int flag);

Perl   - pdq::SetDebug($flag);

Python - pdq.SetDebug(flag)

R      - 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.16  SetDemand

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

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

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

R      - 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.17  SetTUnit

SYNTAX
ANSI C - void PDQ_SetTUnit(char *unitname);

Perl   - pdq::SetTUnit($unitname);

Python - pdq.SetTUnit(unitname)

R      - 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.18  SetVisits

SYNTAX
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      - 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.19  SetWUnit

SYNTAX
ANSI C - void PDQ_SetWUnit(char *unitname);

Perl   - pdq::SetWUnit($unitname);

Python - pdq.SetWUnit(unitname)

R      - 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.20  Solve

SYNTAX
ANSI C - int PDQ_Solve(int method);

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

Python - pdq.Solve(pdq.method)

R      - 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.38.
On 21 Oct 2013, 08:22.