Class shared_connection

Class shared_connection_block

boost::signals2::shared_connection_block — Blocks a connection between a signal and a slot.

Synopsis

// In header: <boost/signals2/shared_connection_block.hpp>


class shared_connection_block {
public:
  // construct/copy/destruct
  shared_connection_block(const boost::signals2::connection & = connection(), 
                          bool = true);
  shared_connection_block(const boost::signals2::shared_connection_block &);
  shared_connection_block& 
  operator=(const boost::signals2::shared_connection_block &);
  ~shared_connection_block();

  // connection blocking
  void unblock();
  void block();
  bool blocking() const;

  // miscellaneous methods
  boost::signals2::connection connection() const;
};

Description

A shared_connection_block object blocks a connection, preventing the associated slot from executing when the associated signal is invoked. The connection will remain blocked until every shared_connection_block that references the connection releases its block. A shared_connection_block releases its block when it is destroyed or its unblock method is called.

A shared_connection_block is safe to use even after the signals2::connection object it was constructed from has been destroyed, or the connection it references has been disconnected.

Note, blocking a connection does not guarantee the associated slot has finished execution if it is already in the process of being run when the connection block goes into effect. This is similar to the behaviour of disconnect, in that blocking a connection will not wait for the connection's associated slot to complete execution. This situation may arise in a multi-threaded environment if the connection block goes into effect concurrently with signal invocation, or in a single-threaded environment if a slot blocks its own connection.

`shared_connection_block` public construct/copy/destruct

shared_connection_block(const boost::signals2::connection & conn = connection(), 
                        bool initially_blocking = true);

Effects:

Creates a shared_connection_block which can block the connection referenced by conn. The shared_connection_block will initially block the connection if and only if the initially_blocking parameter is true. The block on the connection may be released by calling the unblock method, or destroying the shared_connection_block object.

Default construction of a shared_connection_block results in a shared_connection_block which references the NULL connection. Such a shared_connection_block is safe to use, though not particularly useful until it is assigned another shared_connection_block which references a real connection.

Postconditions:

this->blocking() == initially_blocking

shared_connection_block(const boost::signals2::shared_connection_block & other);

Effects:

Copy constructs a shared_connection_block which references the same connection as other.

Postconditions:

this->connection() == other.connection()

this->blocking() == other.blocking()

shared_connection_block& 
operator=(const boost::signals2::shared_connection_block & rhs);

Effects:

Makes this reference the same connection as rhs.

Postconditions:

this->connection() == rhs.connection()

this->blocking() == rhs.blocking()

Throws:

Will not throw.

```
~shared_connection_block();
```
Effects:

If blocking() is true, releases the connection block.

`shared_connection_block` connection blocking

void unblock();

Effects:	If blocking() is true, releases the connection block. Note, the connection may remain blocked due to other `shared_connection_block` objects.
Postconditions:	`this->blocking() == false`.

```
void block();
```
Effects:

If blocking() is false, reasserts a block on the connection.

Postconditions:

this->blocking() == true.

bool blocking() const;

Returns:	`true` if `this` is asserting a block on the connection.
Notes:	`this->blocking() == true` implies `connection::blocked() == true` for the connection. However, `this->blocking() == false` does not necessarily imply `connection::blocked() == false`, since the connection may be blocked by another `shared_connection_block` object.

`shared_connection_block` miscellaneous methods

```
boost::signals2::connection connection() const;
```
Returns:

A connection object for the connection referenced by this.

Effects:	If blocking() is false, reasserts a block on the connection.
Postconditions:	`this->blocking() == true`.