Graph Vertex Methods

pyvgx.Graph Vertex Methods	Description
pyvgx.Graph.CreateVertex()	Creates a new vertex in the graph.
pyvgx.Graph.NewVertex()	Create a new vertex in the graph if it does not already exist, then acquire write access and return the vertex object.
pyvgx.Graph.DeleteVertex()	Delete a vertex from the graph.
pyvgx.Graph.OpenVertex()	Return a pyvgx.Vertex object with the requested access mode.
pyvgx.Graph.OpenVertices()	Acquire multiple vertices and return a list of pyvgx.Vertex objects with the requested access mode.
pyvgx.Graph.CloseVertex()	Release access lock and commit any vertex changes.
pyvgx.Graph.CloseVertices()	Release multiple vertices.
pyvgx.Graph.CloseAll()	Close all vertices opened by current thread.
pyvgx.Graph.CommitAll()	Commit all write-locked vertices opened by current thread.
pyvgx.Graph.EscalateVertex()	Promote vertex access from readonly to writable.
pyvgx.Graph.RelaxVertex()	Relax a writable vertex to readonly access.
pyvgx.Graph.ShowOpenVertices()	Print open vertices to stdout.
pyvgx.Graph.GetOpenVertices()	Return a list of open vertices.

pyvgx.Graph Vertex Methods

Description

pyvgx.Graph.CreateVertex()

Creates a new vertex in the graph.

pyvgx.Graph.NewVertex()

Create a new vertex in the graph if it does not already exist, then acquire write access and return the vertex object.

pyvgx.Graph.DeleteVertex()

Delete a vertex from the graph.

pyvgx.Graph.OpenVertex()

Return a pyvgx.Vertex object with the requested access mode.

pyvgx.Graph.OpenVertices()

Acquire multiple vertices and return a list of pyvgx.Vertex objects with the requested access mode.

pyvgx.Graph.CloseVertex()

Release access lock and commit any vertex changes.

pyvgx.Graph.CloseVertices()

Release multiple vertices.

pyvgx.Graph.CloseAll()

Close all vertices opened by current thread.

pyvgx.Graph.CommitAll()

Commit all write-locked vertices opened by current thread.

pyvgx.Graph.EscalateVertex()

Promote vertex access from readonly to writable.

pyvgx.Graph.RelaxVertex()

Relax a writable vertex to readonly access.

pyvgx.Graph.ShowOpenVertices()

Print open vertices to stdout.

pyvgx.Graph.GetOpenVertices()

Return a list of open vertices.

1. pyvgx.Graph.CreateVertex()

Creates a new vertex in the graph.

1.1. Syntax

pyvgx.Graph.CreateVertex( id[, type[, lifespan[, properties ]]] ) -> 1 or 0

1.2. Parameters

Parameter Type Default Description

Parameter	Type	Default	Description
id	str or bytes		Unique ID string for the vertex to be created
type	str or bytes	None	Type name of the vertex to be created or None
lifespan	int	-1 (infinite)	Maximum age of vertex before automatic deletion
properties	dict	{}	Pairs of { `str` : `object` } to initialize/update vertex properties

str or bytes

Unique ID string for the vertex to be created

type

str or bytes

None

Type name of the vertex to be created or None

lifespan

int

-1 (infinite)

Maximum age of vertex before automatic deletion

properties

dict

{}

Pairs of { str : object } to initialize/update vertex properties

1.3. Return Value

If the vertex is successfully created, this method returns 1. If the vertex already exists, 0 is returned. If the vertex cannot be created, an exception is raised.

1.4. Remarks

This method creates a new vertex in the graph if it does not already exist. The created vertex is not acquired. To gain read or write access to the created vertex it is necessary to call pyvgx.Graph.OpenVertex() or pyvgx.Graph.NewVertex().

The vertex can be assigned an optional type name. By default the vertex will be typeless (None). If the vertex already exists and a type argument is supplied which is different from the existing vertex’s type pyvgx.VertexError is raised. If too many unique vertex types have been used in the graph pyvgx.EnumerationError is raised.

The optional lifespan parameter specifies the maximum vertex age A (in seconds) at which the vertex will be automatically deleted from the graph. Vertices have infinite lifespan by default. This is equivalent to calling pyvgx.Vertex.SetExpiration( expires=A, relative=True ).

The optional properties parameter can be used to assign initial properties to the vertex at creation time. Property keys must be str and property values may be any object supported by pyvgx.Vertex.SetProperty(). If the vertex already exists its properties will be updated.

1.5. Example

import pyvgx
g = pyvgx.Graph("graph")
# -> 1 Create vertex A, typeless
g.CreateVertex( "A" )

# -> 1 Create vertex B, typed
g.CreateVertex( "B", type="thing" )

# -> 0 Vertex B already exists, no action
g.CreateVertex( "B" )

# -> 0 Vertex B already exists, no action
g.CreateVertex( "B", type="thing" )

# Exception, type differs from existing vertex type
g.CreateVertex( "B", type="other" )

A = g.OpenVertex( "A", mode="r" )    # Open A, readonly
B = g.OpenVertex( "B", mode="w" )    # Open B, writable
#
# Do things with A and B
#
g.CloseVertex( A )                    # Close vertex A
g.CloseVertex( B )                    # Close vertex B

# Vertex C will expire after one hour
g.CreateVertex( "C", lifespan=3600 )

# Vertex D has initial properties x and y
g.CreateVertex( "D", properties={'x':1,'y':2} )

2. pyvgx.Graph.NewVertex()

This creates a new vertex in the graph if it does not already exist, then acquires write access and returns the vertex object.

2.1. Syntax

pyvgx.Graph.NewVertex( id[, type[, lifespan[, properties[, timeout ]]]] ) -> pyvgx.Vertex

2.2. Parameters

Parameter Type Default Description

Parameter	Type	Default	Description
id	str		Unique ID string for the vertex to be created, or opened (in write mode) if it does not already exist.
type	str	None	Type name of the vertex to be created, or None to create a typeless vertex.
lifespan	int	-1 (infinite)	Maximum age of vertex before automatic deletion
properties	dict	{}	Pairs of { `str` : `object` } to initialize/update vertex properties
timeout	int	0	Timeout specification for acquiring writable access to the vertex.

str

Unique ID string for the vertex to be created, or opened (in write mode) if it does not already exist.

type

str

None

Type name of the vertex to be created, or None to create a typeless vertex.

lifespan

int

-1 (infinite)

Maximum age of vertex before automatic deletion

properties

dict

{}

Pairs of { str : object } to initialize/update vertex properties

timeout

int

Timeout specification for acquiring writable access to the vertex.

2.3. Return Value

If the vertex is successfully created and/or opened, a pyvgx.Vertex object is returned. If the vertex could not be created or opened, an exception is raised.

2.4. Remarks

The vertex is returned in a writeable state. The current thread owns full read/write access to the vertex. No other threads can read or modify the vertex until released by the current thread.

When write access is no longer needed, the vertex should either be completely released using pyvgx.Graph.CloseVertex() or relaxed to readonly access using pyvgx.Graph.RelaxVertex(). If the Python vertex object goes out of scope it is automatically released.

If the vertex does not already exist, it is created and committed.

The vertex can be assigned an optional type name. By default the vertex will be typeless (None). If the vertex already exists and a type argument is supplied which is different from the existing type pyvgx.VertexError is raised. If too many unique vertex types have been used in the graph pyvgx.EnumerationError is raised.

The optional properties parameter can be used to assign initial properties to the vertex when it is created or update existing properties. Property keys must be str and property values may be any object supported by pyvgx.Vertex.SetProperty().

2.5. Example

import pyvgx
g = pyvgx.Graph("graph")

# Open vertex, writable, create new if necessary, typeless
A = g.NewVertex( "A" )

# Open vertex, writeable, create new if necessary, typed
B = g.NewVertex( "B", type="thing" )

#
# Do things with A and B
#
g.CloseVertex( A )                    # Close vertex A
g.CloseVertex( B )                    # Close vertex B

# New vertex C will expire after one hour
C = g.NewVertex( "C", lifespan=3600 )

# New vertex D has initial properties
D = g.NewVertex( "D", properties={'x':1,'y':2})

3. pyvgx.Graph.DeleteVertex()

Delete a vertex from the graph.

3.1. Syntax

pyvgx.Graph.DeleteVertex( id[, timeout ] ) -> 1 or 0

3.2. Parameters

Parameter	Type	Default	Description
id	str		Unique ID string of the vertex to be deleted
timeout	int	0	Timeout specification for acquiring writable access to the vertex.

Parameter

Type

Default

Description

str

Unique ID string of the vertex to be deleted

timeout

int

Timeout specification for acquiring writable access to the vertex.

3.3. Return Value

If the vertex is successfully deleted, this method returns 1. If the vertex does not exist, 0 is returned. If the vertex could not be deleted, an exception is raised. The exception will indicate whether a timeout or some other error occurred.

3.4. Remarks

This method removes a vertex from the graph. If write access cannot be obtained by the current thread the method will block in accordance with the timeout specified.

If the deleted vertex contains properties, vectors, or outbound relationships (outarcs) to other vertices these will all be removed as well. Inbound relationships (inarcs) will be left intact. If any inarcs exist the vertex will become a VIRTUAL vertex and continue to exist in the graph. If no inarcs exist the vertex will be completely removed from the graph.

If the vertex cannot be acquired within the timeout pyvgx.AccessError is raised.

If the vertex has outarcs and the terminals of those arcs cannot be acquired within the timeout pyvgx.ArcError is raised. The vertex is automatically scheduled for deletion in the background as soon as possible.

If the vertex is already open and writable by the current thread then the delete operation will be allowed to proceed. However, on completion a reference to the internal vertex is still held by the Python pyvgx.Vertex object and the vertex will therefore still exist in the graph but as a VIRTUAL vertex. Once the pyvgx.Vertex object is deleted or goes out of scope the vertex will be removed completely from the graph.

If the current thread owns a readonly lock on the vertex to be deleted then the operation will fail and raise pyvgx.AccessError.

3.5. Note About Readonly Locks

In general, if the current thread holds readonly locks for any vertices then the current thread is prevented from deleting any vertices, even ones that are not yet acquired. This is to prevent a deadlock scenario where the vertex to be deleted has a connection to one of the readonly vertices which would require modification of the arc structure of a readonly vertex. This can never complete, hence the restriction. To perform deletion of a vertex without giving up readonly locks, the readonly locked vertices may be temporarily promoted to writable using pyvgx.Graph.EscalateVertex(), then deleted, and then relaxed back to readonly using pyvgx.Graph.RelaxVertex().

3.6. Example

import pyvgx
g = pyvgx.Graph("graph")

# Create and delete
g.CreateVertex( "A" )        # -> 1 Create vertex A
g.DeleteVertex( "A" )        # -> 1 Delete vertex A
g.DeleteVertex( "A" )        # -> 0 No effect, vertex A does not exist

# Create, delete while holding reference
B = g.NewVertex( "B" )       # Create and open vertex B
g.DeleteVertex( "B" )        # -> 1

# Vertex B is now virtual because Python reference still exists
del B

# Python reference now out of scope, vertex B is deleted from graph

# Delete when readonly vertex is held
g.CreateVertex( "C" )        # -> 1 Create vertex C
g.CreateVertex( "D" )        # -> 1 Create vertex D
C = g.OpenVertex( "C", mode="r" )    # Open vertex C READONLY
g.DeleteVertex( "D" )        # Raises pyvgx.AccessError
g.EscalateVertex( C )        # Promote C to writeable
g.DeleteVertex( "D" )        # -> 1 Delete vertex D
g.RelaxVertex( C )           # Relax C back to readonly
g.DeleteVertex( "C" )        # Raises pyvgx.AccessError
g.EscalateVertex( C )        # Promote C to writable
g.DeleteVertex( "C" )        # -> 1

# Vertex C is now virtual because Python reference still exists
del C

# Python reference now out of scope, vertex C is deleted from graph

4. pyvgx.Graph.OpenVertex()

Return a pyvgx.Vertex object with the requested access mode.

4.1. Syntax

pyvgx.Graph.OpenVertex( id[, mode[, timeout ]] ) -> pyvgx.Vertex

4.2. Parameters

Parameter	Type	Default	Description
id	str		Unique ID string or a memory address for the vertex to be opened
mode	chr	'a'	Access mode is one of: 'r'=Readonly 'w'=Writable (and create typeless) 'a'=Writable (do not create)
timeout	int	0	Timeout specification for acquiring the requested access to the vertex.

Parameter

Type

Default

Description

str

Unique ID string or a memory address for the vertex to be opened

mode

chr

'a'

Access mode is one of:

'r'=Readonly

'w'=Writable (and create typeless)

'a'=Writable (do not create)

timeout

int

Timeout specification for acquiring the requested access to the vertex.

4.3. Return Value

If the vertex is successfully acquired a pyvgx.Vertex object is returned.

4.4. Remarks

This method will acquire a lock on the vertex and return it. If a lock cannot be acquired within the timeout pyvgx.AccessError is raised. Successive calls to this method will lock the vertex recursively. It is necessary to call pyvgx.Graph.CloseVertex() exactly once for each recursive call to pyvgx.Graph.OpenVertex() in order to release the acquired vertex.

If the vertex is opened in readonly mode it cannot be recursively opened in writable mode. To promote a readonly vertex (that has not yet been recursively acquired) to writable use pyvgx.Graph.EscalateVertex().

Recursive acquisition has a limit of 112 levels. Attempting to recursively open a vertex beyond the limit will raise pyvgx.AccessError.

The following acquisition modes are supported:

'r' = Readonly

Open and return the vertex in readonly mode. The vertex is guaranteed to be consistent and unchanged for as long as the current thread holds this lock. Other threads may acquire the same vertex in readonly mode, but will not be able to acquire write access.

The vertex id may be supplied as string or integer for this mode. If an integer is supplied it is assumed to be the raw memory address of the vertex to be opened.

'w' = Writable

Open and return the vertex with full write and read access. If the vertex does not exist it is created. Note that the vertex will be typeless if created this way. If your application requires vertex types other than the default, this access mode should be avoided unless pyvgx.Graph.CreateVertex() or pyvgx.Graph.NewVertex() was used earlier to create the vertex. The current thread will not be able to obtain a writable lock as long as any lock (read or write) is held by another thread.

The vertex id must be string for this mode.

'a' = Writable (do not create)

Open and return the vertex with full write and read access. If the vertex does not exist KeyError is raised. The current thread will not be able to obtain a writable lock as long as any lock (read or write) is held by another thread.

The vertex id may be supplied as string or integer for this mode. If an integer is supplied it is assumed to be the raw memory address of the vertex to be opened.

4.5. Example

import pyvgx
g = pyvgx.Graph("graph")

g.CreateVertex( "A" )                # Create vertex A
A = g.OpenVertex( "A", mode="r" )    # Open A in readonly mode
addrA = A.address

g.CreateVertex( "B" )                # Create vertex B
B = g.OpenVertex( "B", mode="a" )    # Open B in writable mode

C = g.OpenVertex( "C", mode="w" )    # Create and open vertex C

# Raises KeyError since vertex D does not exist
D = g.OpenVertex( "D", mode="r" )

# Raises KeyError since vertex E does not exist
E = g.OpenVertex( "E", mode="a" )

g.CloseVertex( A )                   # Close vertex A
g.CloseVertex( B )                   # Close vertex B
g.CloseVertex( C )                   # Close vertex C

A = g.OpenVertex( addrA )            # Re-open A by its address

# Raises KeyError since address is invalid
F = g.OpenVertex( addr + 7 )

5. pyvgx.Graph.OpenVertices()

Acquire multiple vertices as an atomic operation and return a list of pyvgx.Vertex objects with the requested access mode.

5.1. Syntax

pyvgx.Graph.OpenVertices( idlist[, mode[, timeout ]] ) -> vertex_list

5.2. Parameters

Parameter	Type	Default	Description
idlist	str		List of unique ID strings for vertices to be opened
mode	chr	'a'	Access mode is one of: 'r'=Readonly 'a'=Writable (do not create)
timeout	int	0	Timeout specification for acquiring the requested access to all vertices.

Parameter

Type

Default

Description

idlist

str

List of unique ID strings for vertices to be opened

mode

chr

'a'

Access mode is one of:

'r'=Readonly

'a'=Writable (do not create)

timeout

int

Timeout specification for acquiring the requested access to all vertices.

5.3. Return Value

If all vertices are successfully acquired within the specified timeout a list of pyvgx.Vertex objects is returned.

5.4. Remarks

This method will acquire a lock on each vertex in idlist. If any vertex is already locked (by the current thread) one additional lock will be acquired, i.e. lock recursion is supported. Acquisition timeout applies to the operation as a whole. All vertices must be successfully acquired within the timeout, otherwise pyvgx.AccessError is raised and no vertices are acquired.

Non-existent vertices are not implicitly created. If one or more vertex in idlist does not exist KeyError is raised.

Vertices already opened in readonly cannot be recursively opened in writable mode.

Recursive acquisition has a limit of 112 levels. Attempting to recursively open a vertex beyond the limit will raise pyvgx.AccessError.

The following acquisition modes are supported:

'r' = Readonly: Open and return vertices in readonly mode. Readonly vertices are guaranteed to be consistent and unchanged for as long as the current thread holds the acquired locks. Other threads may acquire one or more of the same vertices in readonly mode, but will not be able to acquire write access.
'a' = Writable (do not create): Open and return existing vertices with full write and read access. If any vertex does not exist KeyError is raised. The current thread will not be able to obtain a writable lock on any vertex as long as it is locked (readonly or writable) by another thread.

When VGX is attached to an output stream all output is halted while one or more vertices are acquired writable via this method. All graph operations performed while at least one writable acquisition by this method is in effect will be queued internally and emitted in bulk as a single transaction once all such acquired vertices have been released.

Consider using pyvgx.Graph.Lock() if the only purpose is to confine a set op graph operations to a single transaction.

5.5. Example

import pyvgx
g = pyvgx.Graph("graph")

g.CreateVertex( "A" )                           # Create vertex A
g.CreateVertex( "B" )                           # Create vertex B
g.CreateVertex( "C" )                           # Create vertex C
g.CreateVertex( "D" )                           # Create vertex D

# Open many vertices at once in 'a' mode (writable)
A, B, C = g.OpenVertices( ["A", "B", "C"] )     # Open A, B and C

# Verify open and writable
A.Writable()                                    # -> True
B.Writable()                                    # -> True
C.Writable()                                    # -> True

# Get another lock for C and open D
C2, D = g.OpenVertices( ["C", "D"] )            # C (recursive) and D

# Try (and fail) to open D and non-existent E
D2, E = g.OpenVertices( ["D", "E"] )            # KeyError for E

# Close many vertices
g.CloseVertices( [A, B, C, D] )                 # Close A, B, C, D

# Still one lock for C
C2.Writable()                                   # -> True

# Close C
g.CloseVertex( C2 )                             # Close C

6. pyvgx.Graph.CloseVertex()

Release access lock and commit any vertex changes.

6.1. Syntax

pyvgx.Graph.CloseVertex( vertex_object ) -> bool

6.2. Parameters

Parameter	Type	Default	Description
vertex_object	pyvgx.Vertex		Vertex object to close

Parameter

Type

Default

Description

vertex_object

pyvgx.Vertex

Vertex object to close

6.3. Return Value

This method returns True if the vertex was released. It returns False if there is no ownership to release.

6.4. Remarks

This method releases one ownership reference for a vertex and commits any changes made to the vertex if no other owners exist. The closed pyvgx.Vertex instance can no longer access the vertex.

Several pyvgx.Vertex objects may reference the same graph vertex object. Each wrapper object owns one reference to the graph vertex. When the wrapper object is deleted it will implicitly call pyvgx.Graph.CloseVertex() when it is garbage collected. If the vertex is closed with an explicit call to pyvgx.Graph.CloseVertex() the wrapper object is still a valid Python object but it has lost its reference to the graph vertex and can no longer be used.

6.5. Example

import pyvgx
g = pyvgx.Graph("graph")

g.CreateVertex( "A" )                # Create vertex A
v1 = g.OpenVertex( "A", mode="w" )   # A opened writable, one owner
v2 = g.OpenVertex( "A", mode="w" )   # A opened writable, two owners
v3 = g.OpenVertex( "A", mode="w" )   # A opened writable, three owners
v4 = g.OpenVertex( "A", mode="w" )   # A opened writable, four owners

# Release one ownership, three owners left
g.CloseVertex( v1 )

# Release one ownership, two owners left
g.CloseVertex( v2 )

# Implicitly release one ownership, one owner left
del v3

# Release one ownership, no owners
g.CloseVertex( v4 )

7. pyvgx.Graph.CloseVertices()

Release access locks for multiple vertices at once and commit any vertex changes.

7.1. Syntax

pyvgx.Graph.CloseVertices( vertex_objects ) -> count

7.2. Parameters

Parameter	Type	Default	Description
vertex_objects	list of pyvgx.Vertex objects		List of one or more vertex objects to close

Parameter

Type

Default

Description

vertex_objects

list of pyvgx.Vertex objects

List of one or more vertex objects to close

7.3. Return Value

This method returns the number of vertices released. If one or more vertices have already been released the returned value is less than the length of vertex_objects.

7.4. Remarks

This method releases one ownership reference for each vertex in vertex_objects and commits any changes made to vertices if no other owners exist.

7.5. Example

import pyvgx
g = pyvgx.Graph("graph")

g.CreateVertex( "A" )                           # Create vertex A
g.CreateVertex( "B" )                           # Create vertex B
g.CreateVertex( "C" )                           # Create vertex C
g.CreateVertex( "D" )                           # Create vertex D

# Open many vertices at once
A, B, C = g.OpenVertices( ["A", "B", "C"] )     # Open A, B and C

# Open C (again) and
C2, D = g.OpenVertices( ["C", "D"] )            # Open C and D

# Close all four
g.CloseVertices( [A, B, C, D] )                 # -> 4

# Try to close all four again (no action)
g.CloseVertices( [A, B, C, D] )                 # -> 0

# Only C2 is still open and will be closed
g.CloseVertices( [A, B, C2, D] )                # -> 1

8. pyvgx.Graph.CloseAll()

Close all vertices opened by current thread.

8.1. Syntax

pyvgx.Graph.CloseAll() -> count

8.2. Return Value

This method returns the number of vertices closed.

8.3. Remarks

Use this method as a convenience to close all vertices owned by the current thread. Vertices opened by other threads are not affected by this call.

8.4. Example

import pyvgx
g = pyvgx.Graph("graph")

A = g.NewVertex( "A" )    # Open new vertex A
B = g.NewVertex( "B" )    # Open new vertex B
C = g.NewVertex( "C" )    # Open new vertex C

# Do something
A['x'] = 1
B['x'] = 2
C['x'] = 3

g.CloseAll()              # Close A, B and C

# Vertices are closed
A.Writable()              # -> False
B.Writable()              # -> False
C.Writable()              # -> False

9. pyvgx.Graph.CommitAll()

Commit all write-locked vertices opened by current thread.

9.1. Syntax

pyvgx.Graph.CommitAll() -> n_writable

9.2. Return Value

This method returns the number of write-locked vertices opened by current thread.

9.3. Remarks

Use this method as a convenience to commit all write-locked vertices owned by the current thread. Vertices opened by other threads are not affected by this call.

9.4. Example

import pyvgx
g = pyvgx.Graph("graph")

A = g.NewVertex( "A" )    # Open new vertex A
B = g.NewVertex( "B" )    # Open new vertex B
C = g.NewVertex( "C" )    # Open new vertex C

# Do something
A['x'] = 1
B['x'] = 2

g.CommitAll()             # Commit changes to A, B

# Vertices are still open
A.Writable()              # -> True
B.Writable()              # -> True
C.Writable()              # -> True

10. pyvgx.Graph.EscalateVertex()

Promote vertex access from readonly to writable.

10.1. Syntax

pyvgx.Graph.EscalateVertex( readonly_vertex_object[, timeout ] ) -> None

10.2. Parameters

Parameter	Type	Default	Description
readonly_vertex_object	pyvgx.Vertex		Vertex instance whose access is readonly and should be promoted to writable
timeout	int Timeout specification	0	Acquisition timeout (in milliseconds)

Parameter

Type

Default

Description

readonly_vertex_object

pyvgx.Vertex

Vertex instance whose access is readonly and should be promoted to writable

timeout

int

Timeout specification

Acquisition timeout (in milliseconds)

10.3. Return Value

If vertex readonly access is successfully promoted to writable the method will return None. Otherwise pyvgx.AccessError is raised.

10.4. Remarks

This method will attempt to change the readonly access of the supplied pyvgx.Vertex instance to writable access. This can be accomplished if no other threads hold readonly locks to the vertex and the current thread has acquired the vertex readonly exactly once. If other threads hold readonly locks to the vertex the escalation operation will block in accordance with the timeout specified and raise pyvgx.AccessError if a timeout occurs.

If the current thread holds more than one readonly lock on the vertex (e.g. opened the same vertex twice for two separate pyvgx.Vertex instances) the operation can never complete. For this reason infinite timeout is disallowed.

In more concise terms, the only scenario where vertex escalation can (and will) succeed is when there exists exactly one read lock on the vertex and that lock is owned by the current thread attempting the escalation.

Attempting to escalate a writable vertex will raise pyvgx.AccessError.

10.5. Example

import pyvgx
g = pyvgx.Graph("graph")

# Create, open readable, then escalate
g.CreateVertex( "A" )                # Create vertex A
A = g.OpenVertex( "A", mode="r" )    # Open A in readonly mode
g.EscalateVertex( A )                # Promote A to writable
A.Writable()                         # -> 1
g.CloseVertex( A )

# Can't escalate if multiple readonly locks
A1 = g.OpenVertex( "A", mode="r" )   # Open A readonly
A2 = g.OpenVertex( "A", mode="r" )   # Open A readonly again
g.EscalateVertex( A1 )               # raise pyvgx.AccessError
g.CloseVertex( A1 )
g.CloseVertex( A2 )

# Can't escalate already writable
A = g.OpenVertex( "A", mode="w" )    # Open A writable
g.EscalateVertex( A )                # raise pyvgx.AccessError

11. pyvgx.Graph.RelaxVertex()

Relax a writable vertex to readonly access.

11.1. Syntax

pyvgx.Graph.RelaxVertex( writable_vertex_object ) -> bool

11.2. Parameters

Parameter	Type	Default	Description
writable_vertex_object	pyvgx.Vertex		Vertex instance whose access is writable and should be relaxed to readonly

Parameter

Type

Default

Description

writable_vertex_object

pyvgx.Vertex

Vertex instance whose access is writable and should be relaxed to readonly

11.3. Return Value

If vertex write lock is successfully released this method will return True. If vertex is still write-locked False is returned.

11.4. Remarks

This method will make an attempt to change the access mode of the supplied pyvgx.Vertex to readonly.

The action taken depends on the existing access of the vertex:

If the vertex was acquired writable exactly once, then the vertex is committed and access changed to readonly.
If the vertex was acquired writable recursively, then one level of write recursion is released (same behavior as pyvgx.Graph.CloseVertex()).
If the vertex was acquired readonly, then no action is performed.

It does not matter how vertex writable access was obtained previously. Relaxing access to readonly is valid for any writable vertex whether it was previously escalated to writable, opened as writable, or just created.

Certain graph operations are not allowed to be performed by the current thread if the current thread holds any readonly vertices. To proceed with such graph operations without giving up access to any acquired readonly vertices (ensuring consistency) the readonly vertices may be temporarily escalated to writable, then relaxed back to readonly once the graph operation is complete. Note that some graph operations are disallowed even though they operate on vertices other than the ones acquired readonly by the current thread. This is a safety measure to eliminate accidental edge cases that would result in a deadlock.

11.5. Example

import pyvgx
g = pyvgx.Graph("graph")

# Create vertex, do something to it, then relax to readonly
A = g.NewVertex( "A" )          # Create vertex A
A.SetProperty( "value", 123 )   # Set a property
g.RelaxVertex( A )              # A is readonly, other threads may access

# Perform a graph operation that does not permit readonly vertices
# in the current thread
g.CreateVertex( "X" )
g.CreateVertex( "Y" )
g.Connect( "X", "to", "Y" )     # raise pyvgx.AccessError
g.EscalateVertex( A )           # Make A writable to allow Connect()
g.Connect( "X", "to", "Y" )     # -> 1 created (X)-[to]->(Y)
g.RelaxVertex( A )              # Relax A back to readonly

12. pyvgx.Graph.ShowOpenVertices()

Print a summary of all vertices in graph that have been acquired.

12.1. Syntax

pyvgx.Graph.ShowOpenVertices() -> None

12.2. Remarks

This method will print a summary of all acquired vertices. The summary includes information about how each vertex is acquired and by which thread.

Useful for debugging.

12.3. Example

import pyvgx
g = pyvgx.Graph("graph")

g.CreateVertex( "A" )
g.CreateVertex( "B" )
C = g.NewVertex( "C" )
D = g.NewVertex( "D" )

A = g.OpenVertex( "A", mode="r" )

g.ShowOpenVertices()

#---------------------------------
#------- Readonly vertices -------
#---------------------------------
#THREAD: 13296
#RO=1   : [1] [__vertex__] [[REAL NORMAL] [IDLE NORMAL - READONLY LOCKED]] [[- -] [- -] [-] [0]] [0]  A
#
#---------------------------------
#------- Writable vertices -------
#---------------------------------
#THREAD: 13296
#WL=1   : [1] [__vertex__] [[REAL NORMAL] [IDLE NORMAL - WRITABLE LOCKED]] [[- -] [- -] [-] [0]] [13296]  C
#WL=1   : [1] [__vertex__] [[REAL NORMAL] [IDLE NORMAL - WRITABLE LOCKED]] [[- -] [- -] [-] [0]] [13296]  D

13. pyvgx.Graph.GetOpenVertices()

Return a list of open vertices in this graph.

13.1. Syntax

pyvgx.Graph.GetOpenVertices( [ threadid ] ) -> list

13.2. Parameters

Parameter	Type	Default	Description
threadid	int	0	When >0, return vertices currently owned by this thread The default is 0, which returns open vertices for all threads

Parameter

Type

Default

Description

threadid

int

When >0, return vertices currently owned by this thread

The default is 0, which returns open vertices for all threads

13.3. Remarks

This method returns a list of all of this graph’s vertices currently acquired by all threads (the default), or by a single thread specified by threadid.

The returned list includes a 3-tuple for each open vertex:

[ ("<vertex_id>", threadid, "<mode>"), ... ]

where <mode> is RO or WL.

Useful for debugging.

13.4. Example

import pyvgx
g = pyvgx.Graph("graph")

g.CreateVertex( "A" )
g.CreateVertex( "B" )
C = g.NewVertex( "C" )
D = g.NewVertex( "D" )

A = g.OpenVertex( "A", mode="r" )

V = g.ShowOpenVertices()

# V = [('A', 13296, 'RO'), ('C', 13296, 'WL'), ('D', 13296, 'WL')]