ZFThread Class Reference

thread utility More...

#include <ZFThread.h>

Inheritance diagram for ZFThread:

Public Types
enum
Public Types inherited from ZFObject
enum

Public Member Functions
virtual const ZFClass *	classData (void)
	get instance's class info
virtual void	sleepCancel ()
	cancel sleep or do nothing if not sleepping
virtual zfstring &	threadName ()
	thread name for debug use
virtual void	threadName (zfstring const &propertyValue)
	see threadName
virtual ZFListener &	threadRunnable ()
	the main callback to run
virtual void	threadRunnable (ZFListener const &propertyValue)
	see threadRunnable
virtual void	threadStart (ZFObject *param0=(zft_zfnull), ZFObject *param1=(zft_zfnull))
	start thread, do nothing if already started
virtual zfbool	threadStarted ()
	return true if start is called and hasn't been stopped or end
virtual zfbool	threadRunning ()
	return true only if thread is running
virtual void	threadStop ()
	request stop the thread, may not be stopped immediately
virtual zfbool	threadStopRequested ()
	return true if stop is called after start
virtual void	threadWait ()
	wait until thread finished running
virtual zfbool	threadWait (zftimet miliSecs)
	wait until thread finished running, or timeout
virtual zfbool	isMainThread ()
	return true if current thread is main thread
virtual zfbool	isNativeThread ()
	true if the thread is registered by nativeThreadRegister
virtual void	autoReleasePoolAdd (ZFObject *obj)
	add object to auto release pool attached to this thread
virtual void	autoReleasePoolDrain ()
	manually drain auto release pool
virtual void	taskQueueInit ()
	prepare a task queue that can be run in this thread
virtual void	taskQueueCleanup ()
	see taskQueueInit
virtual zfbool	taskQueueAvailable ()
	see taskQueueInit
virtual zfindex	taskQueueCount ()
	see taskQueueInit
virtual void	taskQueueAdd (const ZFListener &task)
	see taskQueueInit
virtual void	taskQueueRemove (const ZFListener &task)
	see taskQueueRemove
virtual zfbool	taskQueueRunning ()
	try if any task add by taskQueueAdd is running
Public Member Functions inherited from ZFObject
zfindex	objectRetainCount (void)
	return the object's retain count
void	objectInfoOfInstanceT (zfstring &ret)
	see objectInfoOfInstance
zfstring	objectInfoOfInstance (void)
	return a short string describe the object instance
void	objectInfoT (zfstring &ret)
	see objectInfo
zfstring	objectInfo (void)
	return object info
zfidentity	objectHash (void)
	get hash of this object
ZFCompareResult	objectCompare (ZFObject *anotherObj)
	compare with anotherObj
ZFCompareResult	objectCompareValue (ZFObject *anotherObj)
	explicitly compare object by logical value, see objectCompare
virtual zfauto	invoke (const zfstring &methodName)
	util method to perform ZFDI_invoke, do nothing if fail
virtual zfauto	invoke (const zfstring &methodName, ZFObject *param0, ZFObject *param1=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param2=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param3=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param4=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param5=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param6=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param7=((ZFObject *const &) _ZFP_ZFMP_DEF))
	util method to perform ZFDI_invoke, do nothing if fail
virtual zfbool	invokeT (zfauto &ret, zfstring *errorHint, const zfstring &methodName, ZFObject *param0=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param1=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param2=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param3=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param4=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param5=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param6=((ZFObject *const &) _ZFP_ZFMP_DEF), ZFObject *param7=((ZFObject *const &) _ZFP_ZFMP_DEF))
	util method to perform ZFDI_invoke, do nothing if fail
virtual zfauto	invokeDetail (const zfstring &methodName, const ZFCoreArray< zfauto > &params, zfbool *success=zft_zfnull, zfstring *errorHint=zft_zfnull)
	util method to perform ZFDI_invoke, do nothing if fail
zfbool	objectTagExist (void)
	see objectTag, true if this object has tag, and tag can be checked by objectTagGetAllKeyValue
void	objectTag (const zfstring &key, ZFObject *tag)
	used to hold a object for app's use, auto retained
zfany	objectTag (const zfstring &key)
	see objectTag
void	objectTagGetAllKeyValue (ZFCoreArray< zfstring > &allKey, ZFCoreArray< zfauto > &allValue)
	get all key value
void	objectTagRemove (const zfstring &key)
	remove tag, same as set tag to null
zfauto	objectTagRemoveAndGet (const zfstring &key)
	remove tag, return removed tag or null if not exist
void	objectTagRemoveAll (void)
	remove all tag
void	observerAdd (zfidentity eventId, const ZFListener &observer, ZFLevel observerLevel=ZFLevelAppNormal)
	see observerNotify
void	observerAddForOnce (zfidentity eventId, const ZFListener &observer, ZFLevel observerLevel=ZFLevelAppNormal)
	see observerNotify
void	observerRemove (zfidentity eventId, const ZFListener &callback)
	see observerNotify
void	observerRemoveAll (zfidentity eventId)
	see observerNotify
void	observerRemoveAll (void)
	see observerNotify
zfbool	observerHasAdd (void)
	true if any observer has been added
zfbool	observerHasAdd (zfidentity eventId)
	true if any observer with eventId has been added
void	observerNotify (zfidentity eventId, ZFObject *param0=zft_zfnull, ZFObject *param1=zft_zfnull)
	notify the observer with eventId
void	observerNotifyWithSender (ZFObject *customSender, zfidentity eventId, ZFObject *param0=zft_zfnull, ZFObject *param1=zft_zfnull)
	see observerNotify
void	observerNotifyReversely (zfidentity eventId, ZFObject *param0=zft_zfnull, ZFObject *param1=zft_zfnull)
	see observerNotify
void	observerNotifyReverselyWithSender (ZFObject *customSender, zfidentity eventId, ZFObject *param0=zft_zfnull, ZFObject *param1=zft_zfnull)
	see observerNotify
ZFObserver &	observerHolder (void)
	access the internal observer holder
void	on (const zfstring &eventName, const ZFListener &observer, ZFLevel observerLevel=ZFLevelAppNormal)
	util to observerAdd
void	on (zfidentity eventId, const ZFListener &observer, ZFLevel observerLevel=ZFLevelAppNormal)
	util to observerAdd
void	onInit (const ZFListener &impl)
	util for script to achieve chained call
void	onDealloc (const ZFListener &impl)
	util for script to achieve chained call
zfbool	objectInstanceStateCheck (ZFObjectInstanceState state)
	object instance's state
zfbool	objectInitRunning (void)
	util method to check whether ZFObjectInstanceStateOnInit or ZFObjectInstanceStateOnInitFinish running
zfbool	objectDeallocRunning (void)
	util method to check whether ZFObjectInstanceStateOnDeallocPrepare or ZFObjectInstanceStateOnDealloc running
virtual zfbool	objectIsInternal (void)
	whether this object is internal object or its class is ZFClass::classIsInternal
virtual zfbool	objectIsInternalPrivate (void)
	whether this object is internal private object or its class is ZFClass::classIsInternalPrivate

Static Public Member Functions
static const ZFClass *	ClassData (void)
	get class info
static zfidentity	E_ThreadOnRegister (void)
	see ZFObject::observerNotify
static zfidentity	E_ThreadOnUnregister (void)
	see ZFObject::observerNotify
static zfidentity	E_ThreadOnStart (void)
	see ZFObject::observerNotify
static zfidentity	E_ThreadOnStop (void)
	see ZFObject::observerNotify
static zfidentity	E_ThreadOnStopRequested (void)
	see ZFObject::observerNotify
static zfidentity	E_ThreadTaskQueueOnFinish (void)
	see ZFObject::observerNotify
static void *	nativeThreadRegister (const zfstring &threadName)
	register a thread which is not started by ZFThread, assert fail if already registered
static void	nativeThreadUnregister (void *token)
	see nativeThreadRegister
static zfbool	implAvailable ()
	whether thread impl is available
static zfbool	implMainThreadTaskAvailable ()
	whether mainThread's taskQueueAdd is available
static const ZFCoreArray< ZFThread * > &	allThread ()
	access all thread, mainThread is not included
static ZFThread *	mainThread ()
	return main thread
static ZFThread *	currentThread ()
	return current thread, or zfnull if thread isn't started or registered by ZFThread or not registered by ZFThread::nativeThreadRegister
static zfbool	sleep (zftimet miliSecs)
	make current thread sleep for miliSecs, note this method may be not accurate
static ZFThread *	executeInThread (ZFThread *thread, const ZFListener &callback)
	util to run callback in specified thread, or run in mainThread if the thread is null or taskQueueAvailable is false
Static Public Member Functions inherited from ZFObject
static const ZFClass *	ClassData (void)
	get class info
static zfidentity	E_ObjectBeforeAlloc (void)
	see ZFObject::observerNotify
static zfidentity	E_ObjectAfterAlloc (void)
	see ZFObject::observerNotify
static zfidentity	E_ObjectBeforeDealloc (void)
	see ZFObject::observerNotify
static zfidentity	E_ObjectPropertyValueOnUpdate (void)
	see ZFObject::observerNotify
static zfidentity	E_ObjectPropertyValueOnReset (void)
	see ZFObject::observerNotify

Protected Types
typedef ZFObject	zfsuper
	class ref to super
typedef ZFThread	zfself
	class ref to self
Protected Types inherited from ZFObject
typedef _ZFP_Obj_Base	zfsuper
	class ref to super
typedef ZFObject	zfself
	class ref to self

Protected Member Functions
virtual void	objectOnInit (const ZFListener &runnable)
	init from listener
virtual void	objectOnInit (void)
	override this to init your object
virtual void	objectOnDealloc (void)
	override this to destroy your object
virtual void	objectOnDeallocPrepare (void)
	called before objectOnDealloc, safe to call virtual functions here
virtual void	objectInfoImplAppend (zfstring &ret)
	see objectInfo
virtual void	threadOnRun (const ZFArgs &zfargs)
	internal runnable, do nothing by default, you may override it
virtual void	threadOnRegister (void)
	see E_ThreadOnRegister
virtual void	threadOnUnregister (void)
	see E_ThreadOnUnregister
virtual void	threadOnStart (const ZFArgs &zfargs)
	see E_ThreadOnStart
virtual void	threadOnStop (const ZFArgs &zfargs)
	see E_ThreadOnStop
virtual void	threadOnStopRequested (void)
	see E_ThreadOnStopRequested
virtual void	threadTaskQueueOnFinish (void)
	see E_ThreadTaskQueueOnFinish
Protected Member Functions inherited from ZFObject
virtual void	objectInfoImpl (zfstring &ret)
	see objectInfo
virtual zfidentity	objectHashImpl (void)
	see objectHash
virtual ZFCompareResult	objectCompareImpl (ZFObject *anotherObj)
	see objectCompare
virtual ZFCompareResult	objectCompareValueImpl (ZFObject *anotherObj)
	see objectCompareValue
virtual void	observerOnAdd (zfidentity eventId)
	called when add first observer
virtual void	observerOnRemove (zfidentity eventId)
	called when remove last observer
virtual void	observerOnEvent (const ZFArgs &zfargs)
	notified when observerNotify
virtual void	objectOnInitFinish (void)
	called after objectOnInit, safe to call virtual functions here
virtual void	objectOnRetain (void)
	called to retain object
virtual void	objectOnRelease (void)
	called to release object
virtual void	objectPropertyValueOnUpdate (const ZFProperty *property, const void *oldValue)
	see E_ObjectPropertyValueOnUpdate
virtual void	objectPropertyValueOnReset (const ZFProperty *property)
	see E_ObjectPropertyValueOnReset

Detailed Description

thread utility

you can use thread by one of these method:

• inherit from ZFThread and override ZFThread::threadOnRun
• declare a callback and set as thread's run loop by ZFThread::threadRunnable

for app level code, it's recommended to use zfasync since it may contain thread pool logic

Member Function Documentation

classData()

virtual const ZFClass * ZFThread::classData ( void )

inlinevirtual

get instance's class info

Reimplemented from ZFObject.

Reimplemented in ZFThreadMainThread.

E_ThreadOnRegister()

static zfidentity ZFThread::E_ThreadOnRegister ( void )

static

see ZFObject::observerNotify

called in the same thread of the thread task

E_ThreadOnUnregister()

static zfidentity ZFThread::E_ThreadOnUnregister ( void )

static

see ZFObject::observerNotify

called in the same thread of the thread task

E_ThreadOnStart()

static zfidentity ZFThread::E_ThreadOnStart ( void )

static

see ZFObject::observerNotify

called in the same thread of the thread task, param0 and param1 is the params passed from threadStart

E_ThreadOnStop()

static zfidentity ZFThread::E_ThreadOnStop ( void )

static

see ZFObject::observerNotify

called in the same thread of the thread task, param0 and param1 is the params passed from threadStart

E_ThreadOnStopRequested()

static zfidentity ZFThread::E_ThreadOnStopRequested ( void )

static

see ZFObject::observerNotify

called when threadStop called

E_ThreadTaskQueueOnFinish()

static zfidentity ZFThread::E_ThreadTaskQueueOnFinish ( void )

static

see ZFObject::observerNotify

called when all of taskQueueCount finished

nativeThreadRegister()

static void * ZFThread::nativeThreadRegister ( const zfstring & threadName )

static

register a thread which is not started by ZFThread, assert fail if already registered

return a token for nativeThreadUnregister to unregister

you must call nativeThreadUnregister before the thread ends

you must take good care when calling this method
main thread has no need to register

nativeThreadUnregister()

static void ZFThread::nativeThreadUnregister ( void * token )

static

see nativeThreadRegister

it's safe to unregister in different thread using token

allThread()

static const ZFCoreArray< ZFThread * > & ZFThread::allThread ( )

static

access all thread, mainThread is not included

use with caution, use with ZFCoreMutexLock

sleep()

static zfbool ZFThread::sleep ( zftimet miliSecs )

static

make current thread sleep for miliSecs, note this method may be not accurate

return true if reached to specified time, or false if canceled by sleepCancel

executeInThread()

static ZFThread * ZFThread::executeInThread ( ZFThread * thread, const ZFListener & callback )

static

util to run callback in specified thread, or run in mainThread if the thread is null or taskQueueAvailable is false

return the actual thread that added the task, you may use taskQueueRemove to remove the task

objectOnInit()

virtual void ZFThread::objectOnInit ( void )

protectedvirtual

override this to init your object

subclass must call superclass's objectOnInit before any other code if override
you may also declare objectOnInit with params like this:

zfclass Parent : ... {
    ...
protected:
    virtual void objectOnInit(void) {...};
};
zfclass Child : Parent {
protected:
    // override all parent's objectOnInit is also required,
    // because of function hiding of C++
    zfoverride
    virtual void objectOnInit(void) {
        zfsuper::objectOnInit();
    }
    // custom init entry
    virtual void objectOnInit(Params...) {
        // your extra init steps
        ...
    }
};

Warning

objectOnInit and objectOnDealloc is called as a virtual function, take good care of other virtual function call, use zfself::func() instead of this->func() if necessary, or use objectOnInitFinish/objectOnDeallocPrepare, or declare your own constructor with ZFOBJECT_DECLARE_WITH_CUSTOM_CTOR

Note

(ZFTAG_LIMITATION) due to limitations of C++, if your parent type declared objectOnInit with different params, and your child type want to override part of those objectOnInit, then your child type must also override all objectOnInit that parent declared, otherwise, some may be hidden

for objects that designed not to be allocated by user, you should use ZFOBJECT_PRIVATE_ALLOC, typically usage:

zfclass MyObject : zfextend ZFObject {
    ZFOBJECT_DECLARE(MyObject, ZFObject)
    ZFOBJECT_PRIVATE_ALLOC("should be created by MyObject::instanceForXxx only")
 
public:
    static zfauto instanceForXxx(xxx) {
        // can only be allocated by reflection
        return zfself::ClassData()->newInstance();
    }
};
static void func(void) {
    // MyObject *obj = zfAlloc(MyObject); // would compile error
    zfauto obj = MyObject::instanceForXxx(xxx); // OK
}

Reimplemented from ZFObject.

objectOnDealloc()

virtual void ZFThread::objectOnDealloc ( void )

protectedvirtual

override this to destroy your object

subclass must call superclass's objectOnDealloc after any other code if override
see objectOnInit for more info

Reimplemented from ZFObject.

objectOnDeallocPrepare()

virtual void ZFThread::objectOnDeallocPrepare ( void )

protectedvirtual

called before objectOnDealloc, safe to call virtual functions here

usually used to cleanup resources attached to this object other than self's internal resources

Note

it's ensured safe to retain the object while deallocating, but it's not ensured objectOnDeallocPrepare would only called once for each instance

Reimplemented from ZFObject.

objectInfoImplAppend()

virtual void ZFThread::objectInfoImplAppend ( zfstring & ret )

protectedvirtual

see objectInfo

Reimplemented from ZFObject.

threadRunnable()

virtual ZFListener & ZFThread::threadRunnable ( )

inlinevirtual

the main callback to run

default is invalid callback, called after the builtin threadOnRun
you must make sure thread isn't running when setting new runnable
this value take effects only if you start thread by threadStart

See also

threadStart, threadOnRun, threadWait

threadStart()

virtual void ZFThread::threadStart ( ZFObject * param0 = (zft_zfnull), ZFObject * param1 = (zft_zfnull) )

virtual

start thread, do nothing if already started

Reimplemented in ZFThreadMainThread.

threadStarted()

virtual zfbool ZFThread::threadStarted ( )

virtual

return true if start is called and hasn't been stopped or end

Reimplemented in ZFThreadMainThread.

threadRunning()

virtual zfbool ZFThread::threadRunning ( )

virtual

return true only if thread is running

Reimplemented in ZFThreadMainThread.

threadStop()

virtual void ZFThread::threadStop ( )

virtual

request stop the thread, may not be stopped immediately

if thread is started but not running, this function will cancel the thread's run
otherwise, whether the thread is continue running or stopped, is up to the runnable

See also

threadStopRequested

Reimplemented in ZFThreadMainThread.

threadWait() [1/2]

virtual void ZFThread::threadWait ( )

virtual

wait until thread finished running

return immediately if thread isn't running

note:

• do not wait on thread that has called taskQueueInit without taskQueueCleanup, since it would never end until taskQueueCleanup
• when wait for thread that has called sleep, it would wait until sleep done or sleepCancel called

Reimplemented in ZFThreadMainThread.

threadWait() [2/2]

virtual zfbool ZFThread::threadWait ( zftimet miliSecs )

virtual

wait until thread finished running, or timeout

return true immediately if thread isn't running, or false if wait timeout or error

Reimplemented in ZFThreadMainThread.

isMainThread()

virtual zfbool ZFThread::isMainThread ( )

virtual

return true if current thread is main thread

subclass should not override this method

Reimplemented in ZFThreadMainThread.

autoReleasePoolAdd()

virtual void ZFThread::autoReleasePoolAdd ( ZFObject * obj )

virtual

add object to auto release pool attached to this thread

usually this method is called by zfautoRelease

See also

ZFAutoReleasePool

autoReleasePoolDrain()

virtual void ZFThread::autoReleasePoolDrain ( )

virtual

manually drain auto release pool

must ensure that all objects in pool are safe to release
called automatically after each time that runnable ends

See also

ZFAutoReleasePool

taskQueueInit()

virtual void ZFThread::taskQueueInit ( )

virtual

prepare a task queue that can be run in this thread

normally, thread would be terminated if threadRunnable finished
you may use this method to create a task queue loop, and use taskQueueAdd to run multiple task in this thread in order
once taskQueueInit called, the thread would never end even if all task finished, unless taskQueueCleanup called, this is useful to achieve custom message loop

mainThread is a special case since it already has builtin message loop, and the mainThread is always considered taskQueueInit has been called, the difference:

• taskQueueInit : do nothing
• taskQueueCleanup : do nothing
• taskQueueAdd / taskQueueRemove : similar behavior, but add/remove task to main thread loop queue, available only if implMainThreadTaskAvailable

once taskQueueInit called, you may post runnable to be run in the specified thread by taskQueueAdd

threadOnRun()

virtual void ZFThread::threadOnRun ( const ZFArgs & zfargs )

protectedvirtual

internal runnable, do nothing by default, you may override it

note: called before threadRunnable

---

The documentation for this class was generated from the following file:

• ZFThread.h