Changeset 25614 in vbox for trunk/include
- Timestamp:
- Jan 1, 2010 2:19:06 PM (15 years ago)
- svn:sync-xref-src-repo-rev:
- 56305
- Location:
- trunk/include/iprt
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/include/iprt/err.h
r25602 r25614 859 859 #define VERR_SEM_LV_NOT_OWNER (-374) 860 860 /** An illegal lock upgrade was attempted. */ 861 #define VERR_SEM_LV_ UPGRADE(-375)861 #define VERR_SEM_LV_ILLEGAL_UPGRADE (-375) 862 862 /** @} */ 863 863 -
trunk/include/iprt/lockvalidator.h
r25610 r25614 246 246 247 247 /** 248 * Makes the two records siblings. 249 * 250 * @returns VINF_SUCCESS on success, VERR_SEM_LV_INVALID_PARAMETER if either of 251 * the records are invalid. 252 * @param pRec1 Record 1. 253 * @param pRec2 Record 2. 254 */ 255 RTDECL(int) RTLockValidatorRecMakeSiblings(PRTLOCKVALRECCORE pRec1, PRTLOCKVALRECCORE pRec2); 256 257 /** 248 258 * Initialize a lock validator record. 249 259 * … … 297 307 298 308 /** 309 * Record the specified thread as lock owner and increment the write lock count. 310 * 311 * This function is typically called after acquiring the lock. It accounts for 312 * recursions so it can be used instead of RTLockValidatorRecExclRecursion. Use 313 * RTLockValidatorRecExclReleaseOwner to reverse the effect. 314 * 315 * @param pRec The validator record. 316 * @param hThreadSelf The handle of the calling thread. If not known, 317 * pass NIL_RTTHREAD and we'll figure it out. 318 * @param pSrcPos The source position of the lock operation. 319 * @param fFirstRecursion Set if it is the first recursion, clear if not 320 * sure. 321 */ 322 RTDECL(void) RTLockValidatorRecExclSetOwner(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf, 323 PCRTLOCKVALSRCPOS pSrcPos, bool fFirstRecursion); 324 325 /** 326 * Check the exit order and release (unset) the ownership. 327 * 328 * This is called by routines implementing releasing an exclusive lock, 329 * typically before getting down to the final lock releaseing. Can be used for 330 * recursive releasing instead of RTLockValidatorRecExclUnwind. 331 * 332 * @retval VINF_SUCCESS on success. 333 * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the order is wrong. Will have 334 * done all necessary whining and breakpointing before returning. 335 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 336 * 337 * @param pRec The validator record. 338 * @param fFinalRecursion Set if it's the final recursion, clear if not 339 * sure. 340 */ 341 RTDECL(int) RTLockValidatorRecExclReleaseOwner(PRTLOCKVALRECEXCL pRec, bool fFinalRecursion); 342 343 /** 344 * Clear the lock ownership and decrement the write lock count. 345 * 346 * This is only for special cases where we wish to drop lock validation 347 * recording. See RTLockValidatorRecExclCheckAndRelease. 348 * 349 * @param pRec The validator record. 350 */ 351 RTDECL(void) RTLockValidatorRecExclReleaseOwnerUnchecked(PRTLOCKVALRECEXCL pRec); 352 353 /** 354 * Checks and records a lock recursion. 355 * 356 * @retval VINF_SUCCESS on success. 357 * @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone 358 * thru the motions. 359 * @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru 360 * the motions. 361 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 362 * 363 * @param pRec The validator record. 364 * @param pSrcPos The source position of the lock operation. 365 */ 366 RTDECL(int) RTLockValidatorRecExclRecursion(PRTLOCKVALRECEXCL pRec, PCRTLOCKVALSRCPOS pSrcPos); 367 368 /** 369 * Checks and records a lock unwind (releasing one recursion). 370 * 371 * This should be coupled with called to RTLockValidatorRecExclRecursion. 372 * 373 * @retval VINF_SUCCESS on success. 374 * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone 375 * thru the motions. 376 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 377 * 378 * @param pRec The validator record. 379 */ 380 RTDECL(int) RTLockValidatorRecExclUnwind(PRTLOCKVALRECEXCL pRec); 381 382 /** 383 * Checks and records a mixed recursion. 384 * 385 * An example of a mixed recursion is a writer requesting read access to a 386 * SemRW. 387 * 388 * This should be coupled with called to RTLockValidatorRecExclUnwindMixed. 389 * 390 * @retval VINF_SUCCESS on success. 391 * @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone 392 * thru the motions. 393 * @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru 394 * the motions. 395 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 396 * 397 * @param pRec The validator record it to accounted it to. 398 * @param pRecMixed The validator record it came in on. 399 * @param pSrcPos The source position of the lock operation. 400 */ 401 RTDECL(int) RTLockValidatorRecExclRecursionMixed(PRTLOCKVALRECEXCL pRec, PRTLOCKVALRECCORE pRecMixed, PCRTLOCKVALSRCPOS pSrcPos); 402 403 /** 404 * Checks and records the unwinding of a mixed recursion. 405 * 406 * This should be coupled with called to RTLockValidatorRecExclRecursionMixed. 407 * 408 * @retval VINF_SUCCESS on success. 409 * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone 410 * thru the motions. 411 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 412 * 413 * @param pRec The validator record it was accounted to. 414 * @param pRecMixed The validator record it came in on. 415 */ 416 RTDECL(int) RTLockValidatorRecExclUnwindMixed(PRTLOCKVALRECEXCL pRec, PRTLOCKVALRECCORE pRecMixed); 417 418 /** 419 * Check the exclusive locking order. 420 * 421 * This is called by routines implementing exclusive lock acquisition. 422 * 423 * @retval VINF_SUCCESS on success. 424 * @retval VERR_SEM_LV_WRONG_ORDER if the order is wrong. Will have done all 425 * necessary whining and breakpointing before returning. 426 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 427 * 428 * @param pRec The validator record. 429 * @param hThreadSelf The handle of the calling thread. If not known, 430 * pass NIL_RTTHREAD and we'll figure it out. 431 * @param pSrcPos The source position of the lock operation. 432 */ 433 RTDECL(int) RTLockValidatorRecExclCheckOrder(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf, PCRTLOCKVALSRCPOS pSrcPos); 434 435 /** 436 * Do deadlock detection before blocking on exclusive access to a lock. 437 * 438 * @retval VINF_SUCCESS 439 * @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the 440 * motions. 441 * @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is 442 * already the owner. Gone thru the motions. 443 * @retval VERR_SEM_LV_ILLEGAL_UPGRADE if it's a deadlock on the same lock. 444 * The caller must handle any legal upgrades without invoking this 445 * function (for now). 446 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 447 * 448 * @param pRec The validator record we're blocking on. 449 * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD! 450 * @param pSrcPos The source position of the lock operation. 451 * @param fRecursiveOk Whether it's ok to recurse. 452 */ 453 RTDECL(int) RTLockValidatorRecExclCheckBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf, 454 PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk); 455 456 /** 457 * RTLockValidatorRecExclCheckOrder and RTLockValidatorRecExclCheckBlocking 458 * baked into one call. 459 * 460 * @returns Any of the statuses returned by the two APIs. 461 * @param pRec The validator record. 462 * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD! 463 * @param pSrcPos The source position of the lock operation. 464 * @param fRecursiveOk Whether it's ok to recurse. 465 */ 466 RTDECL(int) RTLockValidatorRecExclCheckOrderAndBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf, 467 PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk); 468 469 /** 299 470 * Initialize a lock validator record for a shared lock. 300 471 * … … 321 492 322 493 /** 323 * Makes the two records siblings. 324 * 325 * @returns VINF_SUCCESS on success, VERR_SEM_LV_INVALID_PARAMETER if either of 326 * the records are invalid. 327 * @param pRec1 Record 1. 328 * @param pRec2 Record 2. 329 */ 330 RTDECL(int) RTLockValidatorRecMakeSiblings(PRTLOCKVALRECCORE pRec1, PRTLOCKVALRECCORE pRec2); 331 332 /** 333 * Check the locking order. 334 * 335 * This is called by routines implementing lock acquisition. 494 * Check the shared locking order. 495 * 496 * This is called by routines implementing shared lock acquisition. 336 497 * 337 498 * @retval VINF_SUCCESS on success. … … 341 502 * 342 503 * @param pRec The validator record. 343 * @param hThread The handle of the calling thread. If not known, 344 * pass NIL_RTTHREAD and this method will figure it 345 * out. 346 * @param pSrcPos The source position of the lock operation. 347 */ 348 RTDECL(int) RTLockValidatorCheckOrder(PRTLOCKVALRECEXCL pRec, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos); 349 350 /** 351 * Do deadlock detection before blocking on a lock. 504 * @param hThreadSelf The handle of the calling thread. If not known, 505 * pass NIL_RTTHREAD and we'll figure it out. 506 * @param pSrcPos The source position of the lock operation. 507 */ 508 RTDECL(int) RTLockValidatorRecSharedCheckOrder(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf, PCRTLOCKVALSRCPOS pSrcPos); 509 510 /** 511 * Do deadlock detection before blocking on shared access to a lock. 352 512 * 353 513 * @retval VINF_SUCCESS … … 356 516 * @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is 357 517 * already the owner. Gone thru the motions. 358 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 359 * 360 * @param pRec The validator record we're blocing on. 361 * @param hThread The current thread. Shall not be NIL_RTTHREAD! 362 * @param enmState The sleep state. 518 * @retval VERR_SEM_LV_ILLEGAL_UPGRADE if it's a deadlock on the same lock. 519 * The caller must handle any legal upgrades without invoking this 520 * function (for now). 521 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 522 * 523 * @param pRec The validator record we're blocking on. 524 * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD! 525 * @param pSrcPos The source position of the lock operation. 363 526 * @param fRecursiveOk Whether it's ok to recurse. 364 * @param pSrcPos The source position of the lock operation. 365 */ 366 RTDECL(int) RTLockValidatorCheckBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThread, 367 RTTHREADSTATE enmState, bool fRecursiveOk, 368 PCRTLOCKVALSRCPOS pSrcPos); 369 370 /** 371 * Do order checking and deadlock detection before blocking on a read/write lock 372 * for exclusive (write) access. 373 * 374 * @retval VINF_SUCCESS 375 * @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the 376 * motions. 377 * @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is 378 * already the owner. Gone thru the motions. 379 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 380 * 381 * @param pWrite The validator record for the writer. 382 * @param pRead The validator record for the readers. 383 * @param hThread The current thread. Shall not be NIL_RTTHREAD! 384 * @param enmState The sleep state. 527 */ 528 RTDECL(int) RTLockValidatorRecSharedCheckBlocking(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf, 529 PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk); 530 531 /** 532 * RTLockValidatorRecSharedCheckOrder and RTLockValidatorRecSharedCheckBlocking 533 * baked into one call. 534 * 535 * @returns Any of the statuses returned by the two APIs. 536 * @param pRec The validator record. 537 * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD! 538 * @param pSrcPos The source position of the lock operation. 385 539 * @param fRecursiveOk Whether it's ok to recurse. 386 * @param pSrcPos The source position of the lock operation. 387 */ 388 RTDECL(int) RTLockValidatorCheckWriteOrderBlocking(PRTLOCKVALRECEXCL pWrite, PRTLOCKVALRECSHRD pRead, 389 RTTHREAD hThread, RTTHREADSTATE enmState, bool fRecursiveOk, 390 PCRTLOCKVALSRCPOS pSrcPos); 391 392 /** 393 * Do order checking and deadlock detection before blocking on a read/write lock 394 * for shared (read) access. 395 * 396 * @retval VINF_SUCCESS 397 * @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the 398 * motions. 399 * @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is 400 * already the owner. Gone thru the motions. 401 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 402 * 403 * @param pRead The validator record for the readers. 404 * @param pWrite The validator record for the writer. 405 * @param hThread The current thread. Shall not be NIL_RTTHREAD! 406 * @param enmState The sleep state. 407 * @param fRecursiveOk Whether it's ok to recurse. 408 * @param pSrcPos The source position of the lock operation. 409 */ 410 RTDECL(int) RTLockValidatorCheckReadOrderBlocking(PRTLOCKVALRECSHRD pRead, PRTLOCKVALRECEXCL pWrite, 411 RTTHREAD hThread, RTTHREADSTATE enmState, bool fRecursiveOk, 412 PCRTLOCKVALSRCPOS pSrcPos); 413 414 /** 415 * Check the exit order and release (unset) the ownership. 416 * 417 * This is called by routines implementing releasing the lock. 540 */ 541 RTDECL(int) RTLockValidatorRecSharedCheckOrderAndBlocking(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf, 542 PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk); 543 544 /** 545 * Adds an owner to a shared locking record. 546 * 547 * Takes recursion into account. This function is typically called after 548 * acquiring the lock in shared mode. 549 * 550 * @param pRead The validator record. 551 * @param hThreadSelf The calling thread and owner. 552 * @param pSrcPos The source position of the lock operation. 553 */ 554 RTDECL(void) RTLockValidatorSharedRecAddOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf, PCRTLOCKVALSRCPOS pSrcPos); 555 556 /** 557 * Removes an owner from a shared locking record. 558 * 559 * Takes recursion into account. This function is typically called before 560 * releaseing the lock. 561 * 562 * @param pRec The validator record. 563 * @param hThreadSelf The calling thread and the owner to remove. 564 */ 565 RTDECL(void) RTLockValidatorSharedRecRemoveOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf); 566 567 /** 568 * Check the exit order and release (unset) the shared ownership. 569 * 570 * This is called by routines implementing releasing the read/write lock. 418 571 * 419 572 * @retval VINF_SUCCESS on success. … … 422 575 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 423 576 * 424 * @param pRec The validator record.425 */426 RTDECL(int) RTLockValidatorCheckAndRelease(PRTLOCKVALRECEXCL pRec);427 428 /**429 * Check the exit order and release (unset) the shared ownership.430 *431 * This is called by routines implementing releasing the read/write lock.432 *433 * @retval VINF_SUCCESS on success.434 * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the order is wrong. Will have435 * done all necessary whining and breakpointing before returning.436 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.437 *438 577 * @param pRead The validator record. 439 * @param hThread The handle of the calling thread. 440 */ 441 RTDECL(int) RTLockValidatorCheckAndReleaseReadOwner(PRTLOCKVALRECSHRD pRead, RTTHREAD hThread); 442 443 /** 444 * Checks and records a lock recursion. 445 * 446 * @retval VINF_SUCCESS on success. 447 * @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone 448 * thru the motions. 449 * @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru 450 * the motions. 451 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 452 * 453 * @param pRec The validator record. 454 * @param pSrcPos The source position of the lock operation. 455 */ 456 RTDECL(int) RTLockValidatorRecordRecursion(PRTLOCKVALRECEXCL pRec, PCRTLOCKVALSRCPOS pSrcPos); 457 458 /** 459 * Checks and records a lock unwind (releasing one recursion). 460 * 461 * This should be coupled with called to RTLockValidatorRecordRecursion. 462 * 463 * @retval VINF_SUCCESS on success. 464 * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone 465 * thru the motions. 466 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 467 * 468 * @param pRec The validator record. 469 */ 470 RTDECL(int) RTLockValidatorUnwindRecursion(PRTLOCKVALRECEXCL pRec); 471 472 /** 473 * Checks and records a read/write lock read recursion done by the writer. 474 * 475 * This should be coupled with called to 476 * RTLockValidatorUnwindReadWriteRecursion. 477 * 478 * @retval VINF_SUCCESS on success. 479 * @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone 480 * thru the motions. 481 * @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru 482 * the motions. 483 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 484 * 485 * @param pRead The validator record for the readers. 486 * @param pWrite The validator record for the writer. 487 */ 488 RTDECL(int) RTLockValidatorRecordReadWriteRecursion(PRTLOCKVALRECEXCL pWrite, PRTLOCKVALRECSHRD pRead, PCRTLOCKVALSRCPOS pSrcPos); 489 490 /** 491 * Checks and records a read/write lock read unwind done by the writer. 492 * 493 * This should be coupled with called to 494 * RTLockValidatorRecordReadWriteRecursion. 495 * 496 * @retval VINF_SUCCESS on success. 497 * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone 498 * thru the motions. 499 * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid. 500 * 501 * @param pRead The validator record for the readers. 502 * @param pWrite The validator record for the writer. 503 */ 504 RTDECL(int) RTLockValidatorUnwindReadWriteRecursion(PRTLOCKVALRECEXCL pWrite, PRTLOCKVALRECSHRD pRead); 505 506 /** 507 * Record the specified thread as lock owner and increment the write lock count. 508 * 509 * This function is typically called after acquiring the lock. 510 * 511 * @returns hThread resolved. Can return NIL_RTHREAD iff we fail to adopt the 512 * alien thread or if pRec is invalid. 513 * 514 * @param pRec The validator record. 515 * @param hThread The handle of the calling thread. If not known, 516 * pass NIL_RTTHREAD and this method will figure it 517 * out. 518 * @param pSrcPos The source position of the lock operation. 519 */ 520 RTDECL(RTTHREAD) RTLockValidatorSetOwner(PRTLOCKVALRECEXCL pRec, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos); 521 522 /** 523 * Clear the lock ownership and decrement the write lock count. 524 * 525 * This is typically called before release the lock. 526 * 527 * @returns The thread handle of the previous owner. NIL_RTTHREAD if the record 528 * is invalid or didn't have any owner. 529 * @param pRec The validator record. 530 */ 531 RTDECL(RTTHREAD) RTLockValidatorUnsetOwner(PRTLOCKVALRECEXCL pRec); 532 533 /** 534 * Adds an owner to a shared locking record. 535 * 536 * Takes recursion into account. This function is typically called after 537 * acquiring the lock. 538 * 539 * @param pRead The validator record. 540 * @param hThread The thread to add. 541 * @param pSrcPos The source position of the lock operation. 542 */ 543 RTDECL(void) RTLockValidatorAddReadOwner(PRTLOCKVALRECSHRD pRead, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos); 544 545 /** 546 * Removes an owner from a shared locking record. 547 * 548 * Takes recursion into account. This function is typically called before 549 * releaseing the lock. 550 * 551 * @param pRead The validator record. 552 * @param hThread The thread to to remove. 553 */ 554 RTDECL(void) RTLockValidatorRemoveReadOwner(PRTLOCKVALRECSHRD pRead, RTTHREAD hThread); 578 * @param hThreadSelf The handle of the calling thread. If not known, 579 * pass NIL_RTTHREAD and we'll figure it out. 580 */ 581 RTDECL(int) RTLockValidatorRecSharedCheckAndRelease(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf); 555 582 556 583 /**
Note:
See TracChangeset
for help on using the changeset viewer.