Object Synchronization Process

Ranks

Dynamically Defined Update Time

Synchronization Method Overview

More detailed descriptions in "GridLAB-D™ Device Model Structure"

Parallelization

More detailed descriptions in "GridLAB-D™ Parallelications

Memory Object Locking

Description

Memory locking is used to prevent non-atomic memory access operations from allowing read/write mishaps, such as illustrated by the following simple example.

Table 1: Memory Object Locking

CPU 0	CPU 1	X	Remark
read X		0
	read X	0
write X+1		1	CPU 0 adds 1 to its value of X
	write X+1	1	CPU 1 adds 1 to its value of X
read X		1	value of X is not 2 as expected
	read X	1	value of X is not 2 as expected

Prior to [Hassayampa (Version 3.0)] the problem is addressed by restricting access to memory using a spin lock:

Table 2: Spin Lock

CPU 0	CPU 1	X	Remark
		0	Initial state
lock X		0	CPU 0 lock ok
read X		0
	lock X	0	CPU 1 blocked
write X+1		1	CPU 0 adds 1 to its value of X
unlock X		1	CPU 1 lock ok
lock X		1	CPU 0 blocked
	read X	1
	write X+1	2	CPU 1 adds 1 to its value of X
	unlock X	2	CPU 0 lock ok
	lock X	2	CPU 1 blocked
read X		2	value of X is 2 as expected
unlock X		2	CPU 1 lock ok
	read X	2	value of X is 2 as expected
	unlock X	2

As of [Hassayampa (Version 3.0)] the problem is addressed by restricting access to memory using a R/W lock:

Table 3: R/W Lock

CPU 0	CPU 1	X	Remark
		0	Initial state
wlock X		0	CPU 0 lock ok
read X		0
	wlock X	0	CPU 1 blocked
write X+1		1	CPU 0 adds 1 to its value of X
unlock X		1	CPU 1 lock ok
rlock X		1	CPU 0 blocked
	read X	1
	write X+1	2	CPU 1 adds 1 to its value of X
	unlock X	2	CPU 0 lock ok
	rlock X	2	CPU 1 lock ok
read X		2	value of X is 2 as expected
	read X	2	value of X is 2 as expected
unlock X		2
	unlock X	2

The advantage of R/W locking is that when only reads are being performed, they are not blocked. Blocking only occurs when a write is being performed. In addition, as of [Hassayampa (Version 3.0)] the gl_get() and gl_set() routines automatically implement the appropriate locking mechanism for the type of run being performed. In the case of single threaded simulation, no locking is performed. For multithreaded simulations, r/w locking is used for all memory access between objects.

Examples

The following examples illustrate good coding practice when using locks.

Coherence locks Be sure to operate on data that needs to remain coherent using a single lock instead of multiple locks. For example, you should use

READLOCK(x_lock);
complex t[] = {x[0], x[1] x[2]};
UNLOCK(x_lock);


rather than using three separately locked data copy operations.

Calculation locks Avoid lengthy calculations while using locks. For example, you should use

READLOCK(x_lock);
complex t = A*x;
UNLOCK(x_key);
WRITELOCK(y_lock);
y = t;
UNLOCK(y_lock);


rather than embedding the calculation inside the safe code region.

Nested locks Although you should avoid nested lock because of possible race conditions, if you must use a nested lock try to put the write lock outside the read lock. For example, you should use

WRITELOCK(y_lock);
READLOCK(x_lock);
x = A*x + B*y;
UNLOCK(x_lock);
UNLOCK(y_lock);


rather than taking the read lock out first because write locks can take much longer to obtain than read locks.

Parameter Value Change Notification

Synopsis

module /class.h

#include "gridlabd.h"
EXPORT_NOTIFY(class);
EXPORT_NOTIFY_PROP(class ,property);
int class ::prenotify(PROPERTY *prop, char *value);
int class ::postnotify(PROPERTY *prop, char *value);

Description

Whenever a property is changed using the module API, a notification is sent to any class that has registered a notifier. If the property notification is used, the notification message will only be sent when the specified property is changed.

Return value

The notifier returns 0 is the notification is not handled and non-zero if it is handled.

Issues

GridLAB-D™ does not mandate using accessors to write properties of objects. As a result, the core cannot guarantee that all changes to object properties will result in notifications.