MongoDB  2.7.0
Public Types | Public Member Functions | Friends | List of all members
mongo::FailPoint Class Reference

A simple thread-safe fail point implementation that can be activated and deactivated, as well as embed temporary data into it. More...

#include <fail_point.h>

Public Types

enum  Mode {
  off, alwaysOn, random, nTimes,
  numModes
}
 
enum  RetCode { fastOff = 0, slowOff, slowOn }
 
typedef AtomicUInt32::WordType ValType
 

Public Member Functions

bool shouldFail ()
 Note: This is not side-effect free - it can change the state to OFF after calling. More...
 
RetCode shouldFailOpenBlock ()
 Checks whether fail point is active and increments the reference counter without decrementing it. More...
 
void shouldFailCloseBlock ()
 Decrements the reference counter. More...
 
void setMode (Mode mode, ValType val=0, const BSONObj &extra=BSONObj())
 Changes the settings of this fail point. More...
 
BSONObj toBSON () const
 

Friends

class ScopedFailPoint
 

Detailed Description

A simple thread-safe fail point implementation that can be activated and deactivated, as well as embed temporary data into it.

The fail point has a static instance, which is represented by a FailPoint object, and dynamic instance, which are all the threads in between shouldFailOpenBlock and shouldFailCloseBlock.

Sample use: // Declared somewhere: FailPoint makeBadThingsHappen;

// Somewhere in the code return false || MONGO_FAIL_POINT(makeBadThingsHappen);

or

// Somewhere in the code MONGO_FAIL_POINT_BLOCK(makeBadThingsHappen, blockMakeBadThingsHappen) { const BSONObj& data = blockMakeBadThingsHappen.getData(); // Do something }

Invariants:

  1. Always refer to _fpInfo first to check if failPoint is active or not before entering fail point or modifying fail point.
  2. Client visible fail point states are read-only when active.

Member Function Documentation

void mongo::FailPoint::setMode ( Mode  mode,
ValType  val = 0,
const BSONObj extra = BSONObj() 
)

Changes the settings of this fail point.

This will turn off the fail point and waits for all dynamic instances referencing this fail point to go away before actually modifying the settings.

Parameters
modethe new mode for this fail point.
valthe value that can have different usage depending on the mode:
- off, alwaysOn: ignored
- random:
- nTimes: the number of times this fail point will be active when
    #shouldFail or #shouldFailOpenBlock is called.
extraarbitrary BSON object that can be stored to this fail point that can be referenced afterwards with #getData. Defaults to an empty document.

Outline:

  1. Deactivates fail point to enter write-only mode
  2. Waits for all current readers of the fail point to finish
  3. Sets the new mode.
bool mongo::FailPoint::shouldFail ( )
inline

Note: This is not side-effect free - it can change the state to OFF after calling.

Returns
true if fail point is active.
void mongo::FailPoint::shouldFailCloseBlock ( )

Decrements the reference counter.

See Also
shouldFailOpenBlock
RetCode mongo::FailPoint::shouldFailOpenBlock ( )
inline

Checks whether fail point is active and increments the reference counter without decrementing it.

Must call shouldFailCloseBlock afterwards when the return value is not fastOff. Otherwise, this will remain read-only forever.

Returns
slowOn if fail point is active.
BSONObj mongo::FailPoint::toBSON ( ) const
Returns
a BSON object showing the current mode and data stored.

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