Description

Defining local resources and custom drivers.

Collaboration diagram for Resources:

Functions
	NewResource (rcName, rcType, func=None, data=None)
	Define a new local resource.

	resource (rcName, rcType, data=None)
	Decorator to define a new local resource.

	NewGate (rcName, rcType, rcSet, func, subscrId=None)
	Define a new gate.

	gate (rcName, rcType, *rcSet)
	Decorator to define a new gate.

	GetLocalRc (func)
	Get resource reference of a decorated local resource or gate.

	NewSignal (sigName, rcType, defaultVal=None)
	Define a new signal.

	NewDriver (drvName, func=None, successState=rcsNoReport, data=None)
	Define a new driver.

	driver (drvName, successState=rcsBusy, data=None)
	Decorator to define a new driver.

	NewDriverResource (drvName, rcName, rcType, writable=True)
	Define a new resource.

Function Documentation

◆ NewResource()

NewResource	(	rcName,
		rcType,
		func = `None`,
		data = `None`
	)

Define a new local resource.

Define a new local resource at '/local/resource/<rcName>'.

'rcName' is the name of the resource, 'rcType' is its type. The resource will
be assigned to the built-in 'resource' driver.

'func' is a function to drive new values and will be called as follows:

    func (rc, val [, data] )

where 'rc' is the resource to be driven and 'val' is the new value to be driven.
'val' can be 'None', which indicates that presently no valid request exists.
For details, see the C API documentation on 'CRcDriver::DriveValue()'.

If 'func == None', the resource is generated as a read-only resource.

'data' is an optional reference to user data that will be passed unchanged
to any 'func' invocations.

For reporting values from the resource, the 'CResource::Report...' methods
have to be used.

The drive function 'func' is responsible for immediately reporting any
value/state changes resulting from a drive operation. If the driven value
immediately reflects the actual state of the resource, this can be done by
calling 'CResource::ReportValue()'. If the new real value is not known
immediately, 'CResource::ReportBusy()' should be called now and the final
up-to-date value be reported later.

◆ resource()

resource	(	rcName,
		rcType,
		data = `None`
	)

Decorator to define a new local resource.

Decorator variant of 'NewResource()'.

This decorator allows to easily define a local writable resource as follows:

|   @resource ( <rcName>, <type> [, <data>] )
|   def MyDriveFunc (rc, val [, data]):
|     ...

◆ NewGate()

NewGate	(	rcName,
		rcType,
		rcSet,
		func,
		subscrId = `None`
	)

Define a new gate.

Define a new gate at '/local/gate/<rcName>'.

A gate is a read-only resource showing a value that is calculated by the
gate function based on values of other resources.

'rcName' is the name of the gate, 'rcType' is its type. The gate will be
assigned to the built-in 'gate' driver.

'rcSet' specifies the resource(s) the gate function depends on.
It may be a single resource or a tuple or list of multiple resources.

'func' is the gate function. It is called as:

    value = func (a, b, c, ...)

'a, b, c, ...' are positional arguments with arbitrary names by which the
values of the 'rcSet' resources are passed. The function must return the
actual value to be reported. If 'None' is returned, a state of 'rcsUnkown'
is reported. A state of 'rcsBusy' is never reported.

'NewGate()' returns a reference to the newly created resource.

Notes on writing gate functions ('func'):

1. Any of the arguments 'a, b, c, ...' may also be 'None' if the respective
   resource has a state of 'rcsUnkown'. This must be considered when writing
   gate functions. For example, to check whether a Boolean resource x is known
   and false, the expression should be 'if x == False: ...' instead of
   'if not x: ...', since in the latter case 'not x' would evaluate as true,
   if x is 'None'. In general, Boolean resource values should always be used
   in conjunction with a comparision. For example, an expression like
   'a and b' may be written as '(a == True) and (b != False)', which implies,
   that a value of 'None' is treated like 'False' for 'a', but like 'True'
   for 'b'.

2. To facilitate gate function writing, especially if the source resources have
   numerical types, 'TypeError' exceptions are caught by the caller and result
   in a return value of 'None'. 'TypeError' exceptions are typically raised
   if one of the arguments of an arithmetic exception is 'None'.

3. The gate function is evaluated whenever a value/state change occurs for
   any of the resources of 'rcSet', but only then. If resources are read
   inside the gate function, they usually must be contained in 'rcSet'.
   It is good practice to not read out resources directly, but only rely
   on the arguments passed to the gate function.

◆ gate()

gate	(		rcName,
			rcType,
		*	rcSet
	)

Decorator to define a new gate.

Decorator variant of 'NewGate()'.

This decorator allows to easily define a gate as follows:

|   @gate ( <gate name>, <type>, <source resources> )
|   def MyGateFunc (a, b, c, ...):
|     ...
|     return ...

◆ GetLocalRc()

GetLocalRc ( func )

Get resource reference of a decorated local resource or gate.

Get a resource reference of a local resource or gate by its decorated function.

This function allows to query a resource object defined by the '@gate' or '@resource'
decorator by a reference to the decorated function.

◆ NewSignal()

NewSignal	(	sigName,
		rcType,
		defaultVal = `None`
	)

Define a new signal.

Define a signal resource under '/local/signal/<sigName>.

◆ NewDriver()

NewDriver	(	drvName,
		func = `None`,
		successState = `rcsNoReport`,
		data = `None`
	)

Define a new driver.

Define a new event-based driver.

'drvName' is the unique local id (LID) of the new driver.

'func' is a function to drive new values and will be called as follows:

    func (rc, vs [, data] )

where 'rc' is the resource to be driven and 'vs' (type 'CRcValueState')
is the new value to be driven. 'vs' can (only) have the states 'rcsValid'
or 'rcsUnknown', where the latter indicates that presently no valid request
exists. For details, see the C API documentation on 'CRcDriver::DriveValue()'.

'data' is an optional reference to user data that can be passed
unchanged to any 'func' invocations.

'(ERcState) successState' determines the automatic reply sent out to the
system before 'func' is invoked. Possible values are:

  - 'rcsNoReport' or 'rcsUnknown' (default):
                  nothing is reported back now; the application must report
                  something soon and should report a valid and up-to-date value
                  later.

  - 'rcsBusy':    'rcsBusy' with the *old* value is reported;
                  the application must report a valid and up-to-date value later.

  - 'rcsValid':   the driven value is reported back; no further action by
                  the driver necessary, but no errors are allowed to happen.

For reporting values from the resource, the 'CResource::Report...'
methods have to be used.

◆ driver()

driver	(	drvName,
		successState = `rcsBusy`,
		data = `None`
	)

Decorator to define a new driver.

Decorator variant of 'NewDriver()'.

This decorator allows to easily define a driver as follows:

|   @driver ( <driver name> [, <success state>] [, <data>] )
|   def MyDriverFunc (rc, vs [, data]):
|     ...

◆ NewDriverResource()

NewDriverResource	(	drvName,
		rcName,
		rcType,
		writable = `True`
	)

Define a new resource.

Define a new resource managed by a custom driver defined by 'NewDriver()'.