WeakReference.chs

-- Copyright (C) 2009 John Millikin <jmillikin@gmail.com>
-- 
-- This program is free software: you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation, either version 3 of the License, or
-- any later version.
-- 
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-- GNU General Public License for more details.
-- 
-- You should have received a copy of the GNU General Public License
-- along with this program.  If not, see <http://www.gnu.org/licenses/>.
-- 
{-# LANGUAGE ForeignFunctionInterface #-}
module CPython.Types.WeakReference
	( Reference
	, Proxy
	, newReference
	, newProxy
	, getObject
	) where
import CPython.Internal

#include <hscpython-shim.h>

newtype Reference = Reference (ForeignPtr Reference)
instance Object Reference where
	toObject (Reference x) = SomeObject x
	fromForeignPtr = Reference

newtype Proxy = Proxy (ForeignPtr Proxy)
instance Object Proxy where
	toObject (Proxy x) = SomeObject x
	fromForeignPtr = Proxy

-- | Return a weak reference for the object. This will always return a new
-- reference, but is not guaranteed to create a new object; an existing
-- reference object may be returned. The second parameter, /callback/, can
-- be a callable object that receives notification when /obj/ is garbage
-- collected; it should accept a single parameter, which will be the weak
-- reference object itself. If ob is not a weakly-referencable object, or if
-- /callback/ is not callable, this will throw a @TypeError@.
-- 
newReference :: (Object obj, Object callback) => obj -> Maybe callback -> IO Reference
newReference obj cb =
	withObject obj $ \objPtr ->
	maybeWith withObject cb $ \cbPtr ->
	{# call PyWeakref_NewRef as ^ #} objPtr cbPtr
	>>= stealObject

-- | Return a weak reference proxy for the object. This will always return a
-- new reference, but is not guaranteed to create a new object; an existing
-- proxy may be returned. The second parameter, /callback/, can be a callable
-- object that receives notification when /obj/ is garbage collected; it
-- should accept a single parameter, which will be the weak reference object
-- itself. If ob is not a weakly-referencable object, or if /callback/ is not
-- callable, this will throw a @TypeError@.
-- 
newProxy :: (Object obj, Object callback) => obj -> Maybe callback -> IO Proxy
newProxy obj cb =
	withObject obj $ \objPtr ->
	maybeWith withObject cb $ \cbPtr ->
	{# call PyWeakref_NewProxy as ^ #} objPtr cbPtr
	>>= stealObject

-- | Return the referenced object from a weak reference. If the referent is
-- no longer live, returns @None@.
-- 
{# fun PyWeakref_GetObject as getObject
	{ withObject* `Reference'
	} -> `SomeObject' peekObject* #}