"""

Implement epicsPV using EpicsCA.PV.  This module emulates the epicsPV
class (by Mark Rivers), which used Geoff Savage's CaChannel.  The point
here is to avoid rewriting all of Mark's code to use EpicsCA.PV

Translation/Simplification:   Matt Newville, Sept 2004

Original notes:

This module defines the epicsPV class, which adds additional features to
Geoff Savage's CaChannel class.

Author:         Mark Rivers
Created:        Sept. 16, 2002.
Modifications:
"""

import EpicsCA

class epicsPV:
   """
   This class provides a simple interface to an Epics PV, built on EpicsCA.PV
      - If a PV name is given at construction, the PV will be connected.
        
      - setMonitor() does nothing -- monitors are used internally to improve
        performance, but no user-supplied callbacks are used
      
      - checkMonitor() returns whether the PV value has changed since the
        last read using getValue, getw(), or array_get().

      - putWait() puts a PV value and waits for it to finish.
   """

   def __init__(self, pvName=None, wait=1):
      """
      Keywords:
         pvName:
            An optional name of an EPICS Process Variable.
         
         wait:
            If wait==1, the PV will connect (or try to!) before returning.
            
       """
      # Invoke the base class initialization
      self.pv = EpicsCA.PV(pvName, wait=wait)

   def setMonitor(self):
      """
      does nothing: EpicsCA.PV uses monitors for performance, but
      user supplied callbacks are not implemented for epicsPV()
      (for user supplied callbacks, use EpicsCA.PV
      """
      return True

   def clearMonitor(self):
      """
      Cancels the effect of a previous call to setMonitor().
      """
      self.pv.clear_monitor()

   def checkMonitor(self):
      """
      Returns 1 to indicate that the PV's value has changed since
      it was last read.
      """
      return self.pv.check_monitor()

   def getControl(self, req_type=None, count=None, wait=1, poll=.01):
      """
      unimplemented for epicsPV using EpicsCA.PV
      """
      return False

   # array_get(), getValue(), and getw() are all equivalent
   def array_get(self):
      return self.pv.get()

   def getw(self):
      return self.pv.get()

   def getValue(self):
      return self.pv.get()

   def putWait(self, value):
      """
      put value, wait for completion before returning
      """
      self.pv.put(value,wait=1)

   def putw(self, value):
      """
      put value, wait for completion before returning
      """
      self.pv.put(value,wait=1)

   def put(self, value):
      """
      put value, return immediately
      """
      self.pv.put(value,wait=0)                  

   def array_put(self, value):
      """
      put value, return immediately
      """
      self.pv.put(value,wait=0)                  

   def pend_io(self):
      """
      wait for epics IO processing
      """
      return self.pv.pend_io()

   def name(self):
      """
      return PV name
      """
      return self.pv.pvname