Internal API

This section is intended to help P4P developers. The API described is not considered a public or stable API. It may change without notice.

Ownership

The ownership relations between the various objects in the C++ extensions are shown in the following diagrams.

• Python objects are blue ovals

• C++ objects are black boxes

• red lines are shared_ptr<>

• green lines are weak_ptr<>

• blue lines are python refs. (aka stored PyObject*)

• dashed lines are explicit breaks of a ref. loop

Type and Value

API Reference

Raw client API

class p4p.client.raw.Context(provider='pva', conf=None, useenv=None, unwrap=None, nt=None, **kws)

Parameters:

• provider (str) – A Provider name. Try “pva” or run Context.providers() for a complete list.

• dict (conf) – Configuration to pass to provider. Depends on provider selected.

• useenv (bool) – Allow the provider to use configuration from the process environment.

• nt (dict) – Controls Automatic Value unwrapping. None uses defaults. Set False to disable

• unwrap (dict) – Legacy Automatic Value unwrapping.

disconnect(name=None)

Clear internal Channel cache, allowing currently unused channels to be implictly closed.

Parameters:

name (str) – None, to clear the entire cache, or a name string to clear only a certain entry.

get(name, handler, request=None)

Begin Fetch of current value of a PV

Parameters:

• name – A single name string or list of name strings

• request – A p4p.Value or string to qualify this request, or None to use a default.

• handler (callable) – Completion notification. Called with a Value, RemoteError, or Cancelled

Returns:

A object with a method cancel() which may be used to abort the operation.

monitor(name, handler, request=None, **kws)

Begin subscription to named PV

Parameters:

• name (str) – PV name string

• handler (callable) – Completion notification. Called with None (FIFO not empty), RemoteError, Cancelled, or Disconnected

• request – A p4p.Value or string to qualify this request, or None to use a default.

• notify_disconnect (bool) – Whether disconnect (and done) notifications are delivered to the callback (as None).

Returns:

A Subscription

put(name, handler, builder=None, request=None, get=True)

Write a new value to a PV.

Parameters:

• name – A single name string or list of name strings

• handler (callable) – Completion notification. Called with None (success), RemoteError, or Cancelled

• builder (callable) – Called when the PV Put type is known. A builder is responsible for filling in the Value to be sent. builder(value)

• request – A p4p.Value or string to qualify this request, or None to use a default.

• get (bool) – Whether to do a Get before the Put. If True then the value passed to the builder callable will be initialized with recent PV values. eg. use this with NTEnum to find the enumeration list.

Returns:

A object with a method cancel() which may be used to abort the operation.

rpc(name, handler, value, request=None)

Perform RPC operation on PV

Parameters:

• name – A single name string or list of name strings

• handler (callable) – Completion notification. Called with a Value, RemoteError, or Cancelled

• request – A p4p.Value or string to qualify this request, or None to use a default.

Returns:

A object with a method cancel() which may be used to abort the operation.

exception p4p.client.raw.RemoteError

Thrown with an error message which has been sent by a server to its remote client

class p4p.client.raw.Subscription(context, name, nt, **kws)

Interface to monitor subscription FIFO

Use method poll() to try to pop an item from the FIFO. None indicates the FIFO is empty, must wait for another Data event before calling poll() again.

complete()==True after poll()==False indicates that no more updates will ever be forthcoming. This is normal (not error) completion.

cancel() aborts the subscription.

Raw server API

class p4p.server.raw.Handler

Skeleton of SharedPV Handler

Use of this as a base class is optional.

onFirstConnect(pv)

Called when the first Client channel is created.

Parameters:

pv (SharedPV) – The SharedPV which this Handler is associated with.

onLastDisconnect(pv)

Called when the last Client channel is closed.

Parameters:

pv (SharedPV) – The SharedPV which this Handler is associated with.

put(pv, op)

Called each time a client issues a Put operation on this Channel.

Parameters:

• pv (SharedPV) – The SharedPV which this Handler is associated with.

• op (ServerOperation) – The operation being initiated.

rpc(pv, op)

Called each time a client issues a Remote Procedure Call operation on this Channel.

Parameters:

• pv (SharedPV) – The SharedPV which this Handler is associated with.

• op (ServerOperation) – The operation being initiated.

class p4p.server.raw.SharedPV(handler=None, initial=None, nt=None, wrap=None, unwrap=None, options=None, **kws)

Shared state Process Variable. Callback based implementation.

Note

if initial=None, the PV is initially closed and must be open()’d before any access is possible.

Parameters:

• handler – A object which will receive callbacks when eg. a Put operation is requested. May be omitted if the decorator syntax is used.

• initial (Value) – An initial Value for this PV. If omitted, :py:meth:`open()`s must be called before client access is possible.

• nt – An object with methods wrap() and unwrap(). eg p4p.nt.NTScalar.

• wrap (callable) – As an alternative to providing ‘nt=’, A callable to transform Values passed to open() and post().

• unwrap (callable) – As an alternative to providing ‘nt=’, A callable to transform Values returned Operations in Put/RPC handlers.

• options (dict) – A dictionary of configuration options.

Creating a PV in the open state, with no handler for Put or RPC (attempts will error).

from p4p.nt import NTScalar
pv = SharedPV(nt=NTScalar('d'), value=0.0)
# ... later
pv.post(1.0)

The full form of a handler object is:

class MyHandler:
    def put(self, pv, op):
        pass
    def rpc(self, pv, op):
        pass
    def onFirstConnect(self): # may be omitted
        pass
    def onLastDisconnect(self): # may be omitted
        pass

pv = SharedPV(MyHandler())

Alternatively, decorators may be used.

pv = SharedPV()
@pv.put
def onPut(pv, op):
    pass

The nt= or wrap= and unwrap= arguments can be used as a convience to allow the open(), post(), and associated Operation.value() to be automatically transform to/from Value and more convienent Python types. See Automatic Value unwrapping

open(value, nt=None, wrap=None, unwrap=None, **kws)

Mark the PV as opened an provide its initial value. This initial value is later updated with post().

Parameters:

value – A Value, or appropriate object (see nt= and wrap= of the constructor).

Any clients which have begun connecting which began connecting while this PV was in the close’d state will complete connecting.

Only those fields of the value which are marked as changed will be stored.

post(value, **kws)

Provide an update to the Value of this PV.

Parameters:

value – A Value, or appropriate object (see nt= and wrap= of the constructor).

Only those fields of the value which are marked as changed will be stored.

Any keyword arguments are forwarded to the NT wrap() method (if applicable). Common arguments include: timestamp= , severity= , and message= .