synchronized.h File Reference

#include <string>

Go to the source code of this file.

Classes
class	xdispatch::synclock
	Provides an easy locking mechanism used to ensure the threadsafety of a code area. More...
Namespaces
namespace	xdispatch
Defines
#define	XDISPATCH_CONCAT(A, B)   A ## B
#define	XDISPATCH_LOCK_VAR(X)   XDISPATCH_CONCAT(xd_synclock_, X)
#define	XDISPATCH_LOCK_VAR_SEM(X)   XDISPATCH_CONCAT( _xd_synclock_sem_, X)
#define	XDISPATCH_LOCK_VAR_ONCE(X)   XDISPATCH_CONCAT( _xd_synclock_once_, X)
#define	XDISPATCH_SYNC_HEADER(lock)
#define	XDISPATCH_SYNC_DECL(id)
#define	XDISPATCH_SYNCHRONIZE(lock)   XDISPATCH_SYNC_HEADER( lock )
	Same as synchronize( lock )
#define	XDISPATCH_SYNCHRONIZED   XDISPATCH_SYNC_DECL( __COUNTER__ )
	Same as synchronized( lock )
#define	synchronize(lock)   XDISPATCH_SYNCHRONIZE(lock)
	This macro is used to implement XDispatch's synchronize keyword.
#define	synchronized   XDISPATCH_SYNCHRONIZED
	This macro is used to implement XDispatch's synchronized keyword.
Functions
void	xdispatch::init_semaphore_for_synclock (void *)

---

Detailed Description

Definition in file synchronized.h.

---

Define Documentation

#define synchronize

(

lock

)

XDISPATCH_SYNCHRONIZE(lock)

This macro is used to implement XDispatch's synchronize keyword.

The lock parameter is an object is a variable of type synclock.

If you're worried about namespace pollution, you can disable this macro by defining the following macro before including xdispatch/dispatch.h:

   #define XDISPATCH_NO_KEYWORDS
   #include <xdispatch/dispatch.h>

See also:

XDISPATCH_SYNCHRONIZE()

Provides an easy way to make certain areas within your code threadsafe. To do so, simply declare a synclock object at some point in your code and pass it every time you need to make sure some area in your code can only be accessed exactly by one thread. Pass the same object to several synchronize() {} areas to ensure that a thread can only be within exactly one of those areas at a time.

    // somewhere declare your lock
    synclock age_lock;

    // the variable that is protected by this lock
    int age = 0;

    // a method that can be called from multiple threads safely
    void increase_age(){

        // this area is completely thread safe. We could
        // use the QDispatchSyncLock object within another
        // area marked the same way and only one of them
        // can be accessed at the same time
        synchronize(age_lock) {
            // everything done in here is threadsafe
            age++;
            std::cout << "Age is" << age;
        }
    }

    // another method that can safely be called from multiple threads
    void check_age(){

        // by re-using the age_lock we ensure that exactly one
        // thread can either be within the synchronize(){} block
        // in increase_age() or within this block
        synchronize(age_lock) {
            if(age > 18 && age < 19)
                std::cout << "Hey wonderful";
        }
    }

Tests have shown that marking your code this way is in no way slower than using a mutex and calling lock() or unlock() every time.

The advantage of using the synchronized keyword over a classical mutex is that even if you throw an exception within your code or have several ways to return from the function it is always ensured that the synchronized area will be unlocked as soon as your program leaves the piece of code within the brackets.

In contrast to synchronized you need to manage the lifetime of the lock object yourself.

Remarks:

Starting with version 0.7.0 of xdispatch you can also use a unique string for identifying the lock. This way you do not need to manage an object all the time but can rather work using string constants, i.e. all you have to write is synchronize("age_lock"){ ... } xdispatch will handle all object managing stuff for you.

See also:

synchronized

Definition at line 273 of file synchronized.h.

#define synchronized   XDISPATCH_SYNCHRONIZED

This macro is used to implement XDispatch's synchronized keyword.

If you're worried about namespace pollution, you can disable this macro by defining the following macro before including xdispatch/dispatch.h:

   #define XDISPATCH_NO_KEYWORDS
   #include <xdispatch/dispatch.h>

See also:

XDISPATCH_SYNCHRONIZED( lock )

Provides an easy way to mark an area within your code threadsafe. To do so, simply enclose the used area with a 'synchronized{ }' statement.

In constrast to synchronize() you can mark individual areas threadsafe only.

    // the variable that is protected by this lock
    int age = 0;

    // a method that can be called from multiple threads safely
    void increase_age(){

        // this area is completely thread safe
        synchronized {
            // everything done in here is threadsafe
            age++;
            std::cout << "Age is" << age;
        }
    }

    // another method that can safely be called from multiple threads
    void check_age(){

        synchronized {
            // everything done in here is threadsafe
            // as well, but can be called at the same
            // time as the synchronized block of increase_age
            if(age > 18 && age < 19)
                std::cout << "Hey wonderful";
        }
    }

Tests have shown that marking your code this way is in no way slower than using a mutex and calling lock() or unlock() every time. However please note that locking is a bit slower than when using synchronize(){} and managing the synclock by yourself. Additionally the internally used synclock objects will exist as long as the entire program is executed and cannot be deleted.

The advantage of using the synchronized keyword over a classical mutex is that even if you throw an exception within your code or have several ways to return from the function it is always ensured that the synchronized area will be unlocked as soon as your program leaves the piece of code within the brackets.

In contrast to synchronized you need to manage the lifetime of the lock object yourself.

See also:

synchronize

Definition at line 277 of file synchronized.h.

#define XDISPATCH_CONCAT	(		A,
			B
	)		A ## B

Definition at line 87 of file synchronized.h.

#define XDISPATCH_LOCK_VAR

(

X

)

XDISPATCH_CONCAT(xd_synclock_, X)

Definition at line 88 of file synchronized.h.

#define XDISPATCH_LOCK_VAR_ONCE

(

X

)

XDISPATCH_CONCAT( _xd_synclock_once_, X)

Definition at line 90 of file synchronized.h.

#define XDISPATCH_LOCK_VAR_SEM

(

X

)

XDISPATCH_CONCAT( _xd_synclock_sem_, X)

Definition at line 89 of file synchronized.h.

#define XDISPATCH_SYNC_DECL

(

id

)

Value:

static ::xdispatch::semaphore XDISPATCH_LOCK_VAR_SEM( id ); \
    static dispatch_once_t XDISPATCH_LOCK_VAR_ONCE( id ) = 0; \
    dispatch_once_f( &XDISPATCH_LOCK_VAR_ONCE( id ), &XDISPATCH_LOCK_VAR_SEM( id ), ::xdispatch::init_semaphore_for_synclock ); \
    XDISPATCH_SYNC_HEADER( XDISPATCH_LOCK_VAR_SEM( id ) )

Definition at line 96 of file synchronized.h.

#define XDISPATCH_SYNC_HEADER

(

lock

)

Value:

for( \
  ::xdispatch::synclock XDISPATCH_LOCK_VAR(__LINE__)( lock, true ) ; \
  XDISPATCH_LOCK_VAR(__LINE__) ; \
  XDISPATCH_LOCK_VAR(__LINE__).unlock() \
  )

Definition at line 91 of file synchronized.h.

#define XDISPATCH_SYNCHRONIZE

(

lock

)

XDISPATCH_SYNC_HEADER( lock )

Same as synchronize( lock )

This macro is available as an alternative when XDISPATCH_NO_KEYWORDS was specified.

See also:

synchronize( lock )

Definition at line 110 of file synchronized.h.

#define XDISPATCH_SYNCHRONIZED   XDISPATCH_SYNC_DECL( __COUNTER__ )

Same as synchronized( lock )

This macro is available as an alternative when XDISPATCH_NO_KEYWORDS was specified.

See also:

synchronized( lock )

Definition at line 120 of file synchronized.h.