/usr/include/cc++/thread.h is in libcommoncpp2-dev 1.8.1-6.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 | // Copyright (C) 1999-2005 Open Source Telecom Corporation.
// Copyright (C) 2006-2010 David Sugar, Tycho Softworks.
//
// 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 2 of the License, or
// (at your option) 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, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// As a special exception, you may use this file as part of a free software
// library without restriction. Specifically, if other files instantiate
// templates or use macros or inline functions from this file, or you compile
// this file and link it with other files to produce an executable, this
// file does not by itself cause the resulting executable to be covered by
// the GNU General Public License. This exception does not however
// invalidate any other reasons why the executable file might be covered by
// the GNU General Public License.
//
// This exception applies only to the code released under the name GNU
// Common C++. If you copy code from other releases into a copy of GNU
// Common C++, as the General Public License permits, the exception does
// not apply to the code that you add in this way. To avoid misleading
// anyone as to the status of such modified files, you must delete
// this exception notice from them.
//
// If you write modifications of your own for GNU Common C++, it is your choice
// whether to permit this exception to apply to your modifications.
// If you do not wish that, delete this exception notice.
//
/**
* @file thread.h
* @short Synchronization and threading services.
**/
#ifndef CCXX_THREAD_H_
#define CCXX_THREAD_H_
#include <cc++/config.h>
#ifndef CCXX_STRING_H_
#include <cc++/string.h>
#endif
#ifndef WIN32
#define CCXX_POSIX
#endif // !WIN32
#include <ctime>
#ifndef WIN32
#include <pthread.h>
#endif // !WIN32
#undef CCXX_USE_WIN32_ATOMIC
#ifndef WIN32
#include <time.h>
#include <signal.h>
#include <unistd.h>
#ifdef _THR_UNIXWARE
#undef PTHREAD_MUTEXTYPE_RECURSIVE
#endif
typedef pthread_t cctid_t;
typedef unsigned long timeout_t;
/*
#if defined(__CYGWIN32__)
__declspec(dllimport) long __stdcall InterlockedIncrement(long *);
__declspec(dllimport) long __stdcall InterlockedDecrement(long *);
__declspec(dllimport) long __stdcall InterlockedExchange(long *, long);
#define CCXX_USE_WIN32_ATOMIC 1
#endif
*/
#else // WIN32
typedef DWORD cctid_t;
typedef DWORD timeout_t;
#define MAX_SEM_VALUE 1000000
#define CCXX_USE_WIN32_ATOMIC 1
#endif // !WIN32
#ifdef HAVE_GCC_CXX_BITS_ATOMIC
#include <ios>
#endif
#ifdef CCXX_NAMESPACES
namespace ost {
#ifdef __BORLANDC__
# if __BORLANDC__ >= 0x0560
using std::time_t;
using std::tm;
# endif
#endif
#endif
#ifdef HAVE_GCC_CXX_BITS_ATOMIC
using namespace __gnu_cxx;
#endif
class __EXPORT Thread;
class __EXPORT ThreadKey;
#define TIMEOUT_INF ~((timeout_t) 0)
#define ENTER_CRITICAL enterMutex();
#define LEAVE_CRITICAL leaveMutex();
#define ENTER_DEFERRED setCancel(cancelDeferred);
#define LEAVE_DEFERRED setCancel(cancelImmediate);
#ifndef WIN32
// These macros override common functions with thread-safe versions. In
// particular the common "libc" sleep() has problems since it normally
// uses SIGARLM (as actually defined by "posix"). The pthread_delay and
// usleep found in libpthread are gaurenteed not to use SIGALRM and offer
// higher resolution. psleep() is defined to call the old process sleep.
#undef sleep
#define psleep(x) (sleep)(x)
#ifdef signal
#undef signal
#endif
#endif // !WIN32
#undef Yield
class __EXPORT Conditional;
class __EXPORT Event;
/**
* The Mutex class is used to protect a section of code so that at any
* given time only a single thread can perform the protected operation.
*
* The Mutex can be used as a base class to protect access in a derived
* class. When used in this manner, the ENTER_CRITICAL and LEAVE_CRITICAL
* macros can be used to specify when code written for the derived class
* needs to be protected by the default Mutex of the derived class, and
* hence is presumed to be 'thread safe' from multiple instance execution.
* One of the most basic Common C++ synchronization object is the Mutex
* class. A Mutex only allows one thread to continue execution at a given
* time over a specific section of code. Mutex's have a enter and leave
* method; only one thread can continue from the Enter until the Leave is
* called. The next thread waiting can then get through. Mutex's are also
* known as "CRITICAL SECTIONS" in win32-speak.
*
* The Mutex is always recursive in that if the same thread invokes
* the same mutex lock multiple times, it must release it multiple times.
* This allows a function to call another function which also happens to
* use the same mutex lock when called directly. This was
* deemed essential because a mutex might be used to block individual file
* requests in say, a database, but the same mutex might be needed to block a
* whole series of database updates that compose a "transaction" for one
* thread to complete together without having to write alternate non-locking
* member functions to invoke for each part of a transaction.
*
* Strangely enough, the original pthread draft standard does not directly
* support recursive mutexes. In fact this is the most common "NP" extension
* for most pthread implementations. Common C++ emulates recursive mutex
* behavior when the target platform does not directly support it.
*
* In addition to the Mutex, Common C++ supports a rwlock class. This
* implements the X/Open recommended "rwlock". On systems which do not
* support rwlock's, the behavior is emulated with a Mutex; however, the
* advantage of a rwlock over a mutex is then entirely lost. There has been
* some suggested clever hacks for "emulating" the behavior of a rwlock with
* a pair of mutexes and a semaphore, and one of these will be adapted for
* Common C++ in the future for platforms that do not support rwlock's
* directly.
*
* @author David Sugar <dyfet@ostel.com>
* @short Mutex lock for protected access.
*/
class __EXPORT Mutex
{
private:
static bool _debug;
String _name;
#ifndef WIN32
#ifndef PTHREAD_MUTEXTYPE_RECURSIVE
int volatile _level;
Thread *volatile _tid;
#endif
/*
* Pthread mutex object. This is protected rather than private
* because some mixed mode pthread operations require a mutex as
* well as their primary pthread object. A good example of this
* is the Event class, as waiting on a conditional object must be
* associated with an accessable mutex. An alternative would be
* to make such classes "friend" classes of the Mutex.
*/
pthread_mutex_t _mutex;
#else // WIN32
# if defined(MUTEX_UNDERGROUND_WIN32_MUTEX) && defined(MUTEX_UNDERGROUND_WIN32_CRITICALSECTION)
# error "Can't determine underground for Mutex"
# endif
#ifdef MUTEX_UNDERGROUND_WIN32_MUTEX
HANDLE _mutex;
#endif
#ifdef MUTEX_UNDERGROUND_WIN32_CRITICALSECTION
CRITICAL_SECTION _criticalSection;
#endif
#endif // WIN32
public:
/**
* The mutex is always initialized as a recursive entity.
*
* @param name of mutex for optional deadlock detection
*/
Mutex(const char *name = NULL);
/**
* Destroying the mutex removes any system resources associated
* with it. If a mutex lock is currently in place, it is presumed
* to terminate when the Mutex is destroyed.
*/
virtual ~Mutex();
/**
* Enable or disable deadlock debugging.
*
* @param mode debug mode.
*/
static void setDebug(bool mode)
{_debug = mode;};
/**
* Enable setting of mutex name for deadlock debug.
*
* @param name for mutex.
*/
inline void nameMutex(const char *name)
{_name = name;};
/**
* Entering a Mutex locks the mutex for the current thread. This
* also can be done using the ENTER_CRITICAL macro or by using the
* ++ operator on a mutex.
*
* @see #leaveMutex
*/
void enterMutex(void);
/**
* Future abi will use enter/leave/test members.
*/
inline void enter(void)
{enterMutex();};
/**
* Future abi will use enter/leave/test members.
*/
inline void leave(void)
{leaveMutex();};
/**
* Future abi will use enter/leave/test members.
*
* @return true if entered.
*/
inline bool test(void)
{return tryEnterMutex();};
/**
* Tries to lock the mutex for the current thread. Behaves like
* #enterMutex , except that it doesn't block the calling thread
* if the mutex is already locked by another thread.
*
* @return true if locking the mutex was succesful otherwise false
*
* @see enterMutex
* @see leaveMutex
*/
bool tryEnterMutex(void);
/**
* Leaving a mutex frees that mutex for use by another thread. If
* the mutex has been entered (invoked) multiple times (recursivily)
* by the same thread, then it will need to be exited the same number
* of instances before it is free for re-use. This operation can
* also be done using the LEAVE_CRITICAL macro or by the -- operator
* on a mutex.
*
* @see #enterMutex
*/
void leaveMutex(void);
};
/**
* The MutexLock class is used to protect a section of code so that at any
* given time only a single thread can perform the protected operation.
*
* It use Mutex to protect operation. Using this class is usefull and
* exception safe. The mutex that has been locked is automatically
* released when the function call stack falls out of scope, so one doesnt
* have to remember to unlock the mutex at each function return.
*
* A common use is
*
* void func_to_protect()
* {
* MutexLock lock(mutex);
* ... operation ...
* }
*
* NOTE: do not declare variable as "MutexLock (mutex)", the mutex will be
* released at statement end.
*
* @author Frediano Ziglio <freddy77@angelfire.com>
* @short Mutex automatic locker for protected access.
*/
class __EXPORT MutexLock
{
private:
Mutex& mutex;
public:
/**
* Acquire the mutex
*
* @param _mutex reference to mutex to aquire.
*/
MutexLock( Mutex& _mutex ) : mutex( _mutex )
{ mutex.enterMutex(); }
/**
* Release the mutex automatically
*/
// this should be not-virtual
~MutexLock()
{ mutex.leaveMutex(); }
};
/**
* The ThreadLock class impliments a thread rwlock for optimal reader performance
* on systems which have rwlock support, and reverts to a simple mutex for those
* that do not.
*
* @author David Sugar <dyfet@ostel.com>
* @short Posix rwlock extension for protected access.
*/
class __EXPORT ThreadLock
{
private:
#ifdef HAVE_PTHREAD_RWLOCK
pthread_rwlock_t _lock;
#else
Mutex mutex;
#endif
public:
/**
* Create a process shared thread lock object.
*/
ThreadLock();
/**
* Destroy a process shared thread lock object.
*/
virtual ~ThreadLock();
/**
* Aquire a read lock for the current object.
*/
void readLock(void);
/**
* Aquire a write lock for the current object.
*/
void writeLock(void);
/**
* Attempt read lock for current object.
*
* @return true on success.
*/
bool tryReadLock(void);
/**
* Attempt write lock for current object.
*
* @return true on success.
*/
bool tryWriteLock(void);
/**
* Release any held locks.
*/
void unlock(void);
};
/**
* The ReadLock class is used to protect a section of code through
* a ThreadLock for "read" access to the member function. The
* ThreadLock is automatically released when the object falls out of
* scope.
*
* A common use is
*
* void func_to_protect()
* {
* ReadLock lock(threadlock);
* ... operation ...
* }
*
* NOTE: do not declare variable as "ReadLock (threadlock)", the
* mutex will be released at statement end.
*
* @author David Sugar <dyfet@gnu.org>
* @short Read mode automatic locker for protected access.
*/
class __EXPORT ReadLock
{
private:
ThreadLock& tl;
public:
/**
* Wait for read access
*
* @param _tl reference to lock to aquire.
*/
ReadLock( ThreadLock& _tl ) : tl( _tl )
{ tl.readLock(); }
/**
* Post the semaphore automatically
*/
// this should be not-virtual
~ReadLock()
{ tl.unlock(); }
};
/**
* The WriteLock class is used to protect a section of code through
* a ThreadLock for "write" access to the member function. The
* ThreadLock is automatically released when the object falls out of
* scope.
*
* A common use is
*
* void func_to_protect()
* {
* WriteLock lock(threadlock);
* ... operation ...
* }
*
* NOTE: do not declare variable as "WriteLock (threadlock)", the
* mutex will be released at statement end.
*
* @author David Sugar <dyfet@gnu.org>
* @short Read mode automatic locker for protected access.
*/
class __EXPORT WriteLock
{
private:
ThreadLock& tl;
public:
/**
* Wait for write access
*
* @param _tl reference to threadlock to aquire.
*/
WriteLock( ThreadLock& _tl ) : tl( _tl )
{ tl.writeLock(); }
/**
* Post the semaphore automatically
*/
// this should be not-virtual
~WriteLock()
{ tl.unlock(); }
};
/**
* The Mutex Counter is a counter variable which can safely be incremented
* or decremented by multiple threads. A Mutex is used to protect access
* to the counter variable (an integer). An initial value can be specified
* for the counter, and it can be manipulated with the ++ and -- operators.
*
* @author David Sugar <dyfet@ostel.com>
* @short Thread protected integer counter.
*/
class __EXPORT MutexCounter : public Mutex
{
private:
volatile int counter;
public:
/**
* Create and optionally name a mutex protected counter.
*
* @param id name for mutex counter, optional for deadlock testing.
*/
MutexCounter(const char *id = NULL);
/**
* Create and optionally name a mutex protected counter with
* an initial value.
*
* @param initial value of counter.
* @param id name of counter, optional for deadlock testing.
*/
MutexCounter(int initial, const char *id = NULL);
friend __EXPORT int operator++(MutexCounter &mc);
friend __EXPORT int operator--(MutexCounter &mc);
};
/**
* The AtomicCounter class offers thread-safe manipulation of an integer
* counter. These are commonly used for building thread-safe "reference"
* counters for C++ classes. The AtomicCounter depends on the platforms
* support for "atomic" integer operations, and can alternately substitute
* a "mutex" if no atomic support exists.
*
* @author Sean Cavanaugh <sean@dimensionalrift.com>
* @short atomic counter operation.
*/
class __EXPORT AtomicCounter
{
#ifndef CCXX_USE_WIN32_ATOMIC
private:
#if defined(HAVE_ATOMIC_AIX)
volatile int counter;
#elif defined(HAVE_GCC_BITS_ATOMIC)
volatile _Atomic_word counter;
#elif defined(HAVE_GCC_CXX_BITS_ATOMIC)
volatile _Atomic_word counter;
// __gnu_cxx::_Atomic_word counter;
#elif defined(HAVE_ATOMIC)
atomic_t atomic;
#else
volatile int counter;
pthread_mutex_t _mutex;
#endif
public:
/**
* Initialize an atomic counter to 0.
*/
AtomicCounter();
/**
* Initialize an atomic counter to a known value.
*
* @param value initial value.
*/
AtomicCounter(int value);
~AtomicCounter();
int operator++(void);
int operator--(void);
int operator+=(int change);
int operator-=(int change);
int operator+(int change);
int operator-(int change);
int operator=(int value);
bool operator!(void);
operator int();
#else
private:
long atomic;
public:
inline AtomicCounter()
{atomic = 0;};
inline AtomicCounter(int value)
{atomic = value;};
inline int operator++(void)
{return InterlockedIncrement(&atomic);};
inline int operator--(void)
{return InterlockedDecrement(&atomic);};
int operator+=(int change);
int operator-=(int change);
inline int operator+(int change)
{return atomic + change;};
inline int operator-(int change)
{return atomic - change;};
inline int operator=(int value)
{return InterlockedExchange(&atomic, value);};
inline bool operator!(void)
{return (atomic == 0) ? true : false;};
inline operator int()
{return atomic;};
#endif
};
#ifndef WIN32
/**
* A conditional variable synchcronization object for one to one and
* one to many signal and control events between processes.
* Conditional variables may wait for and receive signals to notify
* when to resume or perform operations. Multiple waiting threads may
* be woken with a broadcast signal.
*
* @warning While this class inherits from Mutex, the methods of the
* class Conditional just handle the system conditional variable, so
* the user is responsible for calling enterMutex and leaveMutex so as
* to avoid race conditions. Another thing to note is that if you have
* several threads waiting on one condition, not uncommon in thread
* pools, each thread must take care to manually unlock the mutex if
* cancellation occurs. Otherwise the first thread cancelled will
* deadlock the rest of the thread.
*
* @author David Sugar
* @short conditional.
* @todo implement in win32
*/
class __EXPORT Conditional
{
private:
pthread_cond_t _cond;
pthread_mutex_t _mutex;
public:
/**
* Create an instance of a conditional.
*
* @param id name of conditional, optional for deadlock testing.
*/
Conditional(const char *id = NULL);
/**
* Destroy the conditional.
*/
virtual ~Conditional();
/**
* Signal a conditional object and a waiting threads.
*
* @param broadcast this signal to all waiting threads if true.
*/
void signal(bool broadcast);
/**
* Wait to be signaled from another thread.
*
* @param timer time period to wait.
* @param locked flag if already locked the mutex.
*/
bool wait(timeout_t timer = 0, bool locked = false);
/**
* Locks the conditional's mutex for this thread. Remember
* that Conditional's mutex is NOT a recursive mutex!
*
* @see #leaveMutex
*/
void enterMutex(void);
/**
* In the future we will use lock in place of enterMutex since
* the conditional composite is not a recursive mutex, and hence
* using enterMutex may cause confusion in expectation with the
* behavior of the Mutex class.
*
* @see #enterMutex
*/
inline void lock(void)
{enterMutex();};
/**
* Tries to lock the conditional for the current thread.
* Behaves like #enterMutex , except that it doesn't block the
* calling thread.
*
* @return true if locking the mutex was succesful otherwise false
*
* @see enterMutex
* @see leaveMutex
*/
bool tryEnterMutex(void);
inline bool test(void)
{return tryEnterMutex();};
/**
* Leaving a mutex frees that mutex for use by another thread.
*
* @see #enterMutex
*/
void leaveMutex(void);
inline void unlock(void)
{return leaveMutex();};
};
#endif
/**
* A semaphore is generally used as a synchronization object between multiple
* threads or to protect a limited and finite resource such as a memory or
* thread pool. The semaphore has a counter which only permits access by
* one or more threads when the value of the semaphore is non-zero. Each
* access reduces the current value of the semaphore by 1. One or more
* threads can wait on a semaphore until it is no longer 0, and hence the
* semaphore can be used as a simple thread synchronization object to enable
* one thread to pause others until the thread is ready or has provided data
* for them. Semaphores are typically used as a
* counter for protecting or limiting concurrent access to a given
* resource, such as to permitting at most "x" number of threads to use
* resource "y", for example.
*
* @author David Sugar <dyfet@ostel.com>
* @short Semaphore counter for thread synchronization.
*/
class __EXPORT Semaphore
{
private:
#ifndef WIN32
unsigned _count, _waiters;
pthread_mutex_t _mutex;
pthread_cond_t _cond;
#else
HANDLE semObject;
#endif // !WIN32
public:
/**
* The initial value of the semaphore can be specified. An initial
* value is often used When used to lock a finite resource or to
* specify the maximum number of thread instances that can access a
* specified resource.
*
* @param resource specify initial resource count or 0 default.
*/
Semaphore(unsigned resource = 0);
/**
* Destroying a semaphore also removes any system resources
* associated with it. If a semaphore has threads currently waiting
* on it, those threads will all continue when a semaphore is
* destroyed.
*/
virtual ~Semaphore();
/**
* Wait is used to keep a thread held until the semaphore counter
* is greater than 0. If the current thread is held, then another
* thread must increment the semaphore. Once the thread is accepted,
* the semaphore is automatically decremented, and the thread
* continues execution.
*
* The pthread semaphore object does not support a timed "wait", and
* hence to maintain consistancy, neither the posix nor win32 source
* trees support "timed" semaphore objects.
*
* @return false if timed out
* @param timeout period in milliseconds to wait
* @see #post
*/
bool wait(timeout_t timeout = 0);
/**
* Posting to a semaphore increments its current value and releases
* the first thread waiting for the semaphore if it is currently at
* 0. Interestingly, there is no support to increment a semaphore by
* any value greater than 1 to release multiple waiting threads in
* either pthread or the win32 API. Hence, if one wants to release
* a semaphore to enable multiple threads to execute, one must perform
* multiple post operations.
*
* @see #wait
*/
void post(void);
#ifndef WIN32
/**
* Call it after a deferred cancellation to avoid deadlocks.
* From PTHREAD_COND_TIMEDWAIT(3P): A condition wait (whether timed or not)
* is a cancellation point. When the cancelability enable state of a thread
* is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a
* cancellation request while in a condition wait is that the mutex is
* (in effect) re-acquired before calling the first cancellation cleanup handler.
*/
void force_unlock_after_cancellation();
#endif // WIN32
// FIXME: how implement getValue for posix compatibility ?
// not portable...
#if 0
/**
* Get the current value of a semaphore.
*
* @return current value.
*/
int getValue(void);
#endif
};
/**
* The SemaphoreLock class is used to protect a section of code through
* a semaphore so that only x instances of the member function may
* execute concurrently.
*
* A common use is
*
* void func_to_protect()
* {
* SemaphoreLock lock(semaphore);
* ... operation ...
* }
*
* NOTE: do not declare variable as "SemaohoreLock (semaphore)", the
* mutex will be released at statement end.
*
* @author David Sugar <dyfet@gnu.org>
* @short Semaphore automatic locker for protected access.
*/
class __EXPORT SemaphoreLock
{
private:
Semaphore& sem;
public:
/**
* Wait for the semaphore
*/
SemaphoreLock( Semaphore& _sem ) : sem( _sem )
{ sem.wait(); }
/**
* Post the semaphore automatically
*/
// this should be not-virtual
~SemaphoreLock()
{ sem.post(); }
};
/**
* The Event class implements a feature originally found in the WIN32 API;
* event notification. A target thread waits on a resetable Event, and one
* or more other threads can then signal the waiting thread to resume
* execution. A timeout can be used to specify a wait duration in
* milliseconds. The Event class must be reset before it can be used again
* as a trigger. These event objects
* use a trigger/reset mechanism and are related to low level conditional
* variables.
*
* @author: David Sugar <dyfet@ostel.com>
* @short Thread synchornization on event notification.
*/
class __EXPORT Event
{
private:
#ifndef WIN32
pthread_mutex_t _mutex;
pthread_cond_t _cond;
bool _signaled;
int _count;
#else
HANDLE cond;
#endif
public:
Event();
virtual ~Event();
/**
* Once signaled, the Event class must be "reset" before responding
* to a new signal.
*
* @see #signal
*/
void reset(void);
/**
* Signal the event for the waiting thread.
*/
void signal(void);
/**
* Wait either for the event to be signaled by another thread or
* for the specified timeout duration.
*
* @see #signal
* @return true if signaled, false if timed out.
* @param timer timeout in milliseconds to wait for a signal.
*/
bool wait(timeout_t timer);
bool wait(void);
};
/**
* Every thread of execution in an application is created by
* instantiating an object of a class derived from the Thread
* class. Classes derived from Thread must implement the run() method,
* which specifies the code of the thread. The base Thread class
* supports encapsulation of the generic threading methods implemented
* on various target operating systems. This includes the ability to
* start and stop threads in a synchronized and controllable manner,
* the ability to specify thread execution priority, and thread
* specific "system call" wrappers, such as for sleep and yield. A
* thread exception is thrown if the thread cannot be created.
* Threading was the first part of Common C++ I wrote, back when it
* was still the APE library. My goal for Common C++ threading has
* been to make threading as natural and easy to use in C++
* application development as threading is in Java. With this said,
* one does not need to use threading at all to take advantage of
* Common C++. However, all Common C++ classes are designed at least
* to be thread-aware/thread-safe as appropriate and necessary.
*
* Common C++ threading is currently built either from the Posix "pthread"
* library or using the win32 SDK. In that the Posix "pthread" draft
* has gone through many revisions, and many system implementations are
* only marginally compliant, and even then usually in different ways, I
* wrote a large series of autoconf macros found in ost_pthread.m4 which
* handle the task of identifying which pthread features and capabilities
* your target platform supports. In the process I learned much about what
* autoconf can and cannot do for you..
*
* Currently the GNU Portable Thread library (GNU pth) is not directly
* supported in Common C++. While GNU "Pth" doesn't offer direct
* native threading support or benefit from SMP hardware, many of the design
* advantages of threading can be gained from it's use, and the Pth pthread
* "emulation" library should be usable with Common C++. In the future,
* Common C++ will directly support Pth, as well as OS/2 and BeOS native
* threading API's.
*
* Common C++ itself defines a fairly "neutral" threading model that is
* not tied to any specific API such as pthread, win32, etc. This neutral
* thread model is contained in a series of classes which handle threading
* and synchronization and which may be used together to build reliable
* threaded applications.
*
* Common C++ defines application specific threads as objects which are
* derived from the Common C++ "Thread" base class. At minimum the "Run"
* method must be implemented, and this method essentially is the "thread",
* for it is executed within the execution context of the thread, and when
* the Run method terminates the thread is assumed to have terminated.
*
* Common C++ allows one to specify the running priority of a newly created
* thread relative to the "parent" thread which is the thread that is
* executing when the constructor is called. Since most newer C++
* implementations do not allow one to call virtual constructors or virtual
* methods from constructors, the thread must be "started" after the
* constructor returns. This is done either by defining a "starting"
* semaphore object that one or more newly created thread objects can wait
* upon, or by invoking an explicit "start" member function.
*
* Threads can be "suspended" and "resumed". As this behavior is not defined
* in the Posix "pthread" specification, it is often emulated through
* signals. Typically SIGUSR1 will be used for this purpose in Common C++
* applications, depending in the target platform. On Linux, since threads
* are indeed processes, SIGSTP and SIGCONT can be used. On solaris, the
* Solaris thread library supports suspend and resume directly.
*
* Threads can be canceled. Not all platforms support the concept of
* externally cancelable threads. On those platforms and API
* implementations that do not, threads are typically canceled through the
* action of a signal handler.
*
* As noted earlier, threads are considered running until the "Run" method
* returns, or until a cancellation request is made. Common C++ threads can
* control how they respond to cancellation, using setCancellation().
* Cancellation requests can be ignored, set to occur only when a
* cancellation "point" has been reached in the code, or occur immediately.
* Threads can also exit by returning from Run() or by invoking the Exit()
* method.
*
* Generally it is a good practice to initialize any resources the thread may
* require within the constructor of your derived thread class, and to purge
* or restore any allocated resources in the destructor. In most cases, the
* destructor will be executed after the thread has terminated, and hence
* will execute within the context of the thread that requested a join rather
* than in the context of the thread that is being terminated. Most
* destructors in derived thread classes should first call Terminate() to
* make sure the thread has stopped running before releasing resources.
*
* A Common C++ thread is normally canceled by deleting the thread object.
* The process of deletion invokes the thread's destructor, and the
* destructor will then perform a "join" against the thread using the
* Terminate() function. This behavior is not always desirable since the
* thread may block itself from cancellation and block the current "delete"
* operation from completing. One can alternately invoke Terminate()
* directly before deleting a thread object.
*
* When a given Common C++ thread exits on it's own through it's Run()
* method, a "Final" method will be called. This Final method will be called
* while the thread is "detached". If a thread object is constructed through
* a "new" operator, it's final method can be used to "self delete" when
* done, and allows an independent thread to construct and remove itself
* autonomously.
*
* A special global function, getThread(), is provided to identify the thread
* object that represents the current execution context you are running
* under. This is sometimes needed to deliver signals to the correct thread.
* Since all thread manipulation should be done through the Common C++ (base)
* thread class itself, this provides the same functionality as things like
* "pthread_self" for Common C++.
*
* All Common C++ threads have an exception "mode" which determines
* their behavior when an exception is thrown by another Common C++
* class. Extensions to Common C++ should respect the current
* exception mode and use getException() to determine what to do when
* they are about to throw an object. The default exception mode
* (defined in the Thread() constructor) is throwObject, which causes
* a pointer to an instance of the class where the error occured to be
* thrown. Other exception modes are throwException, which causes a
* class-specific exception class to be thrown, and throwNothing,
* which causes errors to be ignored.
*
* As an example, you could try to call the Socket class with an
* invalid address that the system could not bind to. This would
* cause an object of type Socket * to be thrown by default, as the
* default exception mode is throwObject. If you call
* setException(throwException) before the bad call to the Socket
* constructor, an object of type SockException (the exception class
* for class Socket) will be thrown instead.
*
* To determine what exception class is thrown by a given Common C++
* class when the exception mode is set to throwException, search the
* source files for the class you are interested in for a class which
* inherits directly or indirectly from class Exception. This is the
* exception class which would be thrown when the exception mode is
* set to throwException.
*
* The advantage of using throwException versus throwObject is that
* more information is available to the programmer from the thrown
* object. All class-specific exceptions inherit from class
* Exception, which provides a getString() method which can be called
* to get a human-readable error string.
*
* Common C++ threads are often aggregated into other classes to provide
* services that are "managed" from or operate within the context of a
* thread, even within the Common C++ framework itself. A good example of
* this is the TCPSession class, which essentially is a combination of a TCP
* client connection and a separate thread the user can define by deriving a
* class with a Run() method to handle the connected service. This
* aggregation logically connects the successful allocation of a given
* resource with the construction of a thread to manage and perform
* operations for said resource.
*
* Threads are also used in "service pools". In Common C++, a service pool
* is one or more threads that are used to manage a set of resources. While
* Common C++ does not provide a direct "pool" class, it does provide a model
* for their implementation, usually by constructing an array of thread
* "service" objects, each of which can then be assigned the next new
* instance of a given resource in turn or algorithmically.
*
* Threads have signal handlers associated with them. Several signal types
* are "predefined" and have special meaning. All signal handlers are
* defined as virtual member functions of the Thread class which are called
* when a specific signal is received for a given thread. The "SIGPIPE"
* event is defined as a "Disconnect" event since it's normally associated
* with a socket disconnecting or broken fifo. The Hangup() method is
* associated with the SIGHUP signal. All other signals are handled through
* the more generic Signal().
*
* Incidently, unlike Posix, the win32 API has no concept of signals, and
* certainly no means to define or deliver signals on a per-thread basis.
* For this reason, no signal handling is supported or emulated in the win32
* implementation of Common C++ at this time.
*
* In addition to TCPStream, there is a TCPSession class which combines a
* thread with a TCPStream object. The assumption made by TCPSession is that
* one will service each TCP connection with a separate thread, and this
* makes sense for systems where extended connections may be maintained and
* complex protocols are being used over TCP.
*
*
* @author David Sugar <dyfet@ostel.com>
* @short base class used to derive all threads of execution.
*/
class __EXPORT Thread
{
public:
/**
* How to raise error
*/
typedef enum Throw {
throwNothing, /**< continue without throwing error */
throwObject, /**< throw object that cause error (throw this) */
throwException /**< throw an object relative to error */
} Throw;
/**
* How work cancellation
*/
typedef enum Cancel {
cancelInitial=0, /**< used internally, do not use */
cancelDeferred=1, /**< exit thread on cancellation pointsuch as yield */
cancelImmediate, /**< exit befor cancellation */
cancelDisabled, /**< ignore cancellation */
cancelManual, /**< unimplemented (working in progress)
@todo implement */
cancelDefault=cancelDeferred
/**< default you should use this for compatibility instead of deferred */
} Cancel;
/**
* How work suspend
*/
typedef enum Suspend {
suspendEnable, /**< suspend enabled */
suspendDisable /**< suspend disabled, Suspend do nothing */
} Suspend;
#ifndef WIN32
/** @internal */
friend class PosixThread;
#endif
/** @internal */
friend class DummyThread;
private:
friend class Cancellation;
friend class postream_type;
friend class Slog;
Semaphore joinSem;
static Thread* _main;
Thread *_parent;
Cancel _cancel;
Semaphore *_start;
// private data
friend class ThreadImpl;
class ThreadImpl* priv;
public:
static Thread *get(void);
private:
#ifdef WIN32
static unsigned __stdcall Execute(Thread *th);
#endif
// close current thread, free all and call Notify
void close();
private:
char _name[32];
static size_t _autostack;
#ifdef WIN32
DWORD waitHandle(HANDLE obj, timeout_t timeout);
#endif
protected:
/**
* Set the name of the current thread. If the name is passed
* as NULL, then the default name is set (usually object
* pointer).
*
* @param text name to use.
*/
void setName(const char *text);
/**
* All threads execute by deriving the Run method of Thread.
* This method is called after Initial to begin normal operation
* of the thread. If the method terminates, then the thread will
* also terminate after notifying it's parent and calling it's
* Final() method.
*
* @see #Initial
*/
virtual void run(void) = 0;
/**
* A thread that is self terminating, either by invoking exit() or
* leaving it's run(), will have this method called. It can be used
* to self delete the current object assuming the object was created
* with new on the heap rather than stack local, hence one may often
* see final defined as "delete this" in a derived thread class. A
* final method, while running, cannot be terminated or cancelled by
* another thread. Final is called for all cancellation type (even
* immediate).
*
* You can safe delete thread ("delete this") class on final, but
* you should exit ASAP (or do not try to call CommonC++ methods...)
*
* @note A thread cannot delete its own context or join
* itself. To make a thread that is a self running object
* that self-deletes, one has to detach the thread by using
* detach() instead of start().
*
* @see #exit
* @see #run
*/
virtual void final(void);
/**
* The initial method is called by a newly created thread when it
* starts execution. This method is ran with deferred cancellation
* disabled by default. The Initial method is given a separate
* handler so that it can create temporary objects on it's own
* stack frame, rather than having objects created on run() that
* are only needed by startup and yet continue to consume stack space.
*
* @see #run
* @see #final
*/
virtual void initial(void);
/**
* Since getParent() and getThread() only refer to an object of the
* Thread "base" type, this virtual method can be replaced in a
* derived class with something that returns data specific to the
* derived class that can still be accessed through the pointer
* returned by getParent() and getThread().
*
* @return pointer to derived class specific data.
*/
virtual void* getExtended(void);
/**
* When a thread terminates, it now sends a notification message
* to the parent thread which created it. The actual use of this
* notification is left to be defined in a derived class.
*
* @param - the thread that has terminated.
*/
virtual void notify(Thread*);
/**
* Used to properly exit from a Thread derived run() or initial()
* method. Terminates execution of the current thread and calls
* the derived classes final() method.
*/
void exit(void);
/**
* Used to wait for a join or cancel, in place of explicit exit.
*/
void sync(void);
/**
* test a cancellation point for deferred thread cancellation.
*/
bool testCancel(void);
/**
* Sets thread cancellation mode. Threads can either be set immune to
* termination (cancelDisabled), can be set to terminate when
* reaching specific "thread cancellation points"
* (cancelDeferred)
* or immediately when Terminate is requested (cancelImmediate).
*
* @param mode for cancellation of the current thread.
*/
void setCancel(Cancel mode);
/**
* Sets the thread's ability to be suspended from execution. The
* thread may either have suspend enabled (suspendEnable) or
* disabled (suspendDisable).
*
* @param mode for suspend.
*/
void setSuspend(Suspend mode);
/**
* Used by another thread to terminate the current thread. Termination
* actually occurs based on the current setCancel() mode. When the
* current thread does terminate, control is returned to the requesting
* thread. terminate() should always be called at the start of any
* destructor of a class derived from Thread to assure the remaining
* part of the destructor is called without the thread still executing.
*/
void terminate(void);
/**
* clear parent thread relationship.
*/
inline void clrParent(void)
{_parent = NULL;};
public:
/**
* This is actually a special constructor that is used to create a
* thread "object" for the current execution context when that context
* is not created via an instance of a derived Thread object itself.
* This constructor does not support First.
*
* @param isMain bool used if the main "thread" of the application.
*/
Thread(bool isMain);
/**
* When a thread object is contructed, a new thread of execution
* context is created. This constructor allows basic properties
* of that context (thread priority, stack space, etc) to be defined.
* The starting condition is also specified for whether the thread
* is to wait on a semaphore before begining execution or wait until
* it's start method is called.
*
* @param pri thread base priority relative to it's parent.
* @param stack space as needed in some implementations.
*/
Thread(int pri = 0, size_t stack = 0);
#ifndef WIN32
/**
* A thread of execution can also be specified by cloning an existing
* thread. The existing thread's properties (cancel mode, priority,
* etc), are also duplicated.
*
* @param th currently executing thread object to clone.
* @todo implement in win32
*/
Thread(const Thread &th);
#endif
/**
* The thread destructor should clear up any resources that have
* been allocated by the thread. The desctructor of a derived
* thread should begin with Terminate() and is presumed to then
* execute within the context of the thread causing terminaton.
*/
virtual ~Thread();
/**
* Set base stack limit before manual stack sizes have effect.
*
* @param size stack size to set, or use 0 to clear autostack.
*/
static void setStack(size_t size = 0)
{_autostack = size;};
/**
* A thread-safe sleep call. On most Posix systems, "sleep()"
* is implimented with SIGALRM making it unusable from multipe
* threads. Pthread libraries often define an alternate "sleep"
* handler such as usleep(), nanosleep(), or nap(), that is thread
* safe, and also offers a higher timer resolution.
*
* @param msec timeout in milliseconds.
*/
static void sleep(timeout_t msec);
/**
* Yields the current thread's CPU time slice to allow another thread to
* begin immediate execution.
*/
static void yield(void);
/**
* When a new thread is created, it does not begin immediate
* execution. This is because the derived class virtual tables
* are not properly loaded at the time the C++ object is created
* within the constructor itself, at least in some compiler/system
* combinations. The thread can either be told to wait for an
* external semaphore, or it can be started directly after the
* constructor completes by calling the start() method.
*
* @return error code if execution fails.
* @param start optional starting semaphore to alternately use.
*/
int start(Semaphore *start = 0);
/**
* Start a new thread as "detached". This is an alternative
* start() method that resolves some issues with later glibc
* implimentations which incorrectly impliment self-detach.
*
* @return error code if execution fails.
* @param start optional starting semaphore to alternately use.
*/
int detach(Semaphore *start = 0);
/**
* Gets the pointer to the Thread class which created the current
* thread object.
*
* @return a Thread *, or "(Thread *)this" if no parent.
*/
inline Thread *getParent(void)
{return _parent;};
/**
* Suspends execution of the selected thread. Pthreads do not
* normally support suspendable threads, so the behavior is
* simulated with signals. On systems such as Linux that
* define threads as processes, SIGSTOP and SIGCONT may be used.
*/
void suspend(void);
/**
* Resumes execution of the selected thread.
*/
void resume(void);
/**
* Used to retrieve the cancellation mode in effect for the
* selected thread.
*
* @return cancellation mode constant.
*/
inline Cancel getCancel(void)
{return _cancel;};
/**
* Verifies if the thread is still running or has already been
* terminated but not yet deleted.
*
* @return true if the thread is still executing.
*/
bool isRunning(void) const;
/**
* Check if this thread is detached.
*
* @return true if the thread is detached.
*/
bool isDetached(void) const;
/**
* Blocking call which unlocks when thread terminates.
*/
void join(void);
/**
* Tests to see if the current execution context is the same as
* the specified thread object.
*
* @return true if the current context is this object.
*/
bool isThread(void) const;
/**
* Get system thread numeric identifier.
*
* @return numeric identifier of this thread.
*/
cctid_t getId(void) const;
/**
* Get the name string for this thread, to use in
* debug messages.
*
* @return debug name.
*/
const char *getName(void) const
{return _name;};
/**
* Get exception mode of the current thread.
*
* @return exception mode.
*/
static Throw getException(void);
/**
* Set exception mode of the current thread.
*
* @return exception mode.
*/
static void setException(Throw mode);
/**
* Signal the semaphore that the specified thread is waiting for
* before beginning execution.
*
* @param th specified thread.
*/
friend inline void operator++(Thread &th)
{if (th._start) th._start->post();};
friend inline void operator--(Thread &th)
{if (th._start) th._start->wait();};
#ifdef WIN32
bool isCancelled() const;
static DWORD waitThread(HANDLE hRef, timeout_t timeout);
#endif
/**
* This is used to help build wrapper functions in libraries
* around system calls that should behave as cancellation
* points but don't.
*
* @return saved cancel type.
*/
static Cancel enterCancel(void);
/**
* This is used to restore a cancel block.
*
* @param cancel type that was saved.
*/
static void exitCancel(Cancel cancel);
};
/**
* A class to automatically set the thread cancellation mode of a
* member function. When the member function returns and the automatic
* variable falls out of scope, the previous thread cancellation mode
* is restored.
*
* @author David Sugar <dyfet@gnu.org>
* @short Automatic cancellation mode setting.
*/
class __EXPORT Cancellation
{
private:
Thread::Cancel prior;
public:
Cancellation(Thread::Cancel cancel);
~Cancellation();
};
#if !defined(WIN32) && !defined(__MINGW32__)
typedef int signo_t;
class PosixThread: public Thread
{
private:
#ifndef WIN32
/** @internal */
friend class ThreadImpl;
friend class Thread;
#endif
#ifndef CCXX_SIG_THREAD_ALARM
static PosixThread *_timer;
static Mutex _arm;
#endif
time_t _alarm;
static void signalThread(Thread* th,signo_t signo);
protected:
/**
* In the Posix version of Common C++, this can be used to send a
* signal into the parent thread of the current object.
*
* @param signo a posix signal id.
*/
inline void signalParent(signo_t signo)
{ signalThread(_parent,signo); };
/**
* In the Posix version of Common C++, this can be used to send a
* signal into the main application thread.
*
* @param signo a posix signal id.
*/
inline void signalMain(signo_t signo)
{ signalThread(_main,signo);};
/**
* A derivable method to call when a SIGALRM is being delivered
* to a specific thread.
*/
virtual void onTimer(void);
/**
* A derived method to handle hangup events being delivered
* to a specific thread.
*/
virtual void onHangup(void);
/**
* A derived method to call when a SIGABRT is being delivered
* to a specific thread.
*/
virtual void onException(void);
/**
* A derived method to call when a SIGPIPE is being delivered
* to a specific thread.
*/
virtual void onDisconnect(void);
/**
* A derived method to handle asynchronous I/O requests delivered
* to the specified thread.
*/
virtual void onPolling(void);
/**
* A derivable method to call for delivering a signal event to
* a specified thread.
*
* @param - posix signal id.
*/
virtual void onSignal(int);
/**
* Used to specify a timeout event that can be delivered to the
* current thread via SIGALRM. When the timer expires, the onTimer()
* method is called for the thread. At present, only one thread
* timer can be active at any given time. On some operating
* systems (including Linux) a timer can be active on each thread.
*
* @param timer timeout in milliseconds.
* @param periodic should the timer be periodic.
* @note currently, periodic timers are only available on
* systems with a working setitimer call.
*/
void setTimer(timeout_t timer, bool periodic = false);
/**
* Gets the time remaining for the current threads timer before
* it expires.
*
* @return time remaining before timer expires in milliseconds.
*/
timeout_t getTimer(void) const;
/**
* Terminates the timer before the timeout period has expired.
* This prevents the timer from sending it's SIGALRM and makes
* the timer available to other threads.
*/
void endTimer(void);
#if defined(HAVE_SIGWAIT) || defined(HAVE_SIGWAIT2)
/**
* Used to wait on a Posix signal from another thread. This can be
* used as a crude rondevious/synchronization method between threads.
*
* @param signo a posix signal id.
*/
void waitSignal(signo_t signo);
#endif
/**
* Used to enable or disable a signal within the current thread.
*
* @param signo posix signal id.
* @param active set to true to enable.
*/
void setSignal(int signo, bool active);
/**
* Access to pthread_attr structure
* this allows setting/modifying pthread attributes
* not covered in the platform independant Thread constructor,
* e.g. contention scope or scheduling policy
*/
pthread_attr_t *getPthreadAttrPtr(void);
/**
* Get pthread_t of underlying posix thread (useful for
* debugging/logging)
*/
pthread_t getPthreadId(void);
public:
PosixThread(int pri = 0, size_t stack = 0);
/**
* Delivers a Posix signal to the current thread.
*
* @param signo a posix signal id.
*/
inline void signalThread(int signo)
{signalThread(this, signo);};
/**
* Install a signal handler for use by threads and
* the OnSignal() event notification handler.
*
* @param signo posix signal id.
*/
static void sigInstall(int signo);
};
#endif
/**
* This class allows the creation of a thread context unique "pointer"
* that can be set and retrieved and can be used to create thread specific
* data areas for implementing "thread safe" library routines.
*
* Finally, Common C++ supports a
* thread-safe "AtomicCounter" class. This can often be used for reference
* counting without having to protect the counter with a separate Mutex
* counter. This lends to lighter-weight code.
*
*
* @author David Sugar <dyfet@ostel.com>
* @short container for thread specific data storage.
*/
class __EXPORT ThreadKey
{
private:
#ifndef WIN32
pthread_key_t key;
typedef void (*TDestruct)(void*);
friend class ThreadImpl;
ThreadKey(TDestruct destruct);
#else
DWORD key;
#endif
public:
/**
* Create a unique thread specific container.
*/
ThreadKey();
/**
* Destroy a thread specific container and any contents reserved.
*/
virtual ~ThreadKey();
/**
* Get the value of the pointer for the thread specific data
* container. A unique pointer can be set for each execution
* context.
*
* @return a unique void * for each execution context.
*/
void *getKey(void);
/**
* Set the value of the pointer for the current thread specific
* execution context. This can be used to store thread context
* specific data.
*
* @param - ptr to thread context specific data.
*/
void setKey(void *);
};
/**
* Timer ports are used to provide synchronized timing events when managed
* under a "service thread" such as SocketService. This is made into a
* stand-alone base class since other derived libraries (such as the
* serial handlers) may also use the pooled "service thread" model
* and hence also require this code for managing timing.
*
* @author David Sugar <dyfet@ostel.com>
* @short synchronized millisecond timing for service threads.
*/
class __EXPORT TimerPort
{
#ifndef WIN32
struct timeval timer;
#else
DWORD timer;
#endif
bool active;
public:
/**
* Create a timer, mark it as inactive, and set the initial
* "start" time to the creation time of the timer object. This
* allows "incTimer" to initially refer to time delays relative
* to the original start time of the object.
*/
TimerPort();
/**
* Set a new start time for the object based on when this call is
* made and optionally activate the timer for a specified number
* of milliseconds. This can be used to set the starting time
* of a realtime session.
*
* @param timeout delay in milliseconds from "now"
*/
void setTimer(timeout_t timeout = 0);
/**
* Set a timeout based on the current time reference value either
* from object creation or the last setTimer(). This reference
* can be used to time synchronize realtime data over specified
* intervals and force expiration when a new frame should be
* released in a synchronized manner.
*
* @param timeout delay in milliseconds from reference.
*/
void incTimer(timeout_t timeout);
/**
* Adjust a timeout based on the current time reference value either
* from object creation or the last setTimer(). This reference
* can be used to time synchronize realtime data over specified
* intervals and force expiration when a new frame should be
* released in a synchronized manner.
*
* @param timeout delay in milliseconds from reference.
*/
void decTimer(timeout_t timeout);
/**
* Sleep until the current timer expires. This is useful in time
* syncing realtime periodic tasks.
*/
void sleepTimer(void);
/**
* This is used to "disable" the service thread from expiring
* the timer object. It does not effect the reference time from
* either creation or a setTimer().
*/
void endTimer(void);
/**
* This is used by service threads to determine how much time
* remains before the timer expires based on a timeout specified
* in setTimer() or incTimer(). It can also be called after
* setting a timeout with incTimer() to see if the current timeout
* has already expired and hence that the application is already
* delayed and should skip frame(s).
*
* return time remaining in milliseconds, or TIMEOUT_INF if
* inactive.
*/
timeout_t getTimer(void) const;
/**
* This is used to determine how much time has elapsed since a
* timer port setTimer benchmark time was initially set. This
* allows one to use setTimer() to set the timer to the current
* time and then measure elapsed time from that point forward.
*
* return time elapsed in milliseconds, or TIMEOUT_INF if
* inactive.
*/
timeout_t getElapsed(void) const;
};
// FIXME: not in win32 implementation
#if !defined(WIN32)
// FIXME: private declaration ???
struct timespec *getTimeout(struct timespec *spec, timeout_t timeout);
#if !defined(__CYGWIN32__) && !defined(__MINGW32__)
void wait(signo_t signo);
#endif
#endif // !WIN32
#ifdef USE_POLL
/**
* The poller class is used to help manage pollfd structs for use in the
* updated serial and socket "port" code.
*
* @author Gianni Mariani <gianni@mariani.ws>
* @short pollfd assistance class for port classes.
*/
class Poller
{
private:
int nufds;
pollfd *ufds;
public:
Poller();
virtual ~Poller();
/**
* reserve a specified number of poll descriptors. If additional
* descriptors are needed, they are allocated.
*
* @return new array of descriptors.
* @param cnt number of desctiptors to reserve
*/
pollfd *getList(int cnt);
/**
* Retreive the current array of poll descriptors.
*
* @return array of descriptors.
*/
inline pollfd *getList(void)
{return ufds;};
};
#endif
inline Thread *getThread(void)
{return Thread::get();}
/**
* This class is used to access non-reentrant date and time functions in the
* standard C library.
*
* The class has two purposes:
* - 1 To be used internaly in CommonCpp's date and time classes to make them
* thread safe.
* - 2 To be used by clients as thread safe replacements to the standard C
* functions, much like Thread::sleep() represents a thread safe version
* of the standard sleep() function.
*
* @note The class provides one function with the same name as its equivalent
* standard function and one with another, unique name. For new clients,
* the version with the unique name is recommended to make it easy to
* grep for accidental usage of the standard functions. The version with
* the standard name is provided for existing clients to sed replace their
* original version.
*
* @note Also note that some functions that returned pointers have been redone
* to take that pointer as an argument instead, making the caller
* responsible for memory allocation/deallocation. This is almost
* how POSIX specifies *_r functions (reentrant versions of the
* standard time functions), except the POSIX functions also return the
* given pointer while we do not. We don't use the *_r functions as they
* aren't all generally available on all platforms yet.
*
* @author Idar Tollefsen <idar@cognita.no>
* @short Thread safe date and time functions.
*/
class __EXPORT SysTime
{
private:
static Mutex timeLock;
protected:
inline static void lock(void)
{timeLock.enterMutex();}
inline static void unlock(void)
{timeLock.leaveMutex();}
public:
static time_t getTime(time_t *tloc = NULL);
static time_t time(time_t *tloc)
{ return getTime(tloc); };
static int getTimeOfDay(struct timeval *tp);
static int gettimeofday(struct timeval *tp, struct timezone *)
{ return getTimeOfDay(tp); };
static struct tm *getLocalTime(const time_t *clock, struct tm *result);
static struct tm *locatime(const time_t *clock, struct tm *result)
{ return getLocalTime(clock, result); };
static struct tm *getGMTTime(const time_t *clock, struct tm *result);
static struct tm *gmtime(const time_t *clock, struct tm *result)
{ return getGMTTime(clock, result);};
};
#ifndef HAVE_LOCALTIME_R
inline struct tm *localtime_r(const time_t *t, struct tm *b)
{return SysTime::getLocalTime(t, b);};
inline char *ctime_r(const time_t *t, char *buf)
{return ctime(t);};
inline struct tm *gmtime_r(const time_t *t, struct tm *b) \
{return SysTime::getGMTTime(t, b);};
inline char *asctime_r(const struct tm *tm, char *b) \
{return asctime(tm);};
#endif
#ifdef CCXX_NAMESPACES
}
#endif
#endif
/** EMACS **
* Local variables:
* mode: c++
* c-basic-offset: 4
* End:
*/
|