Класс choicechoice Class

Блок обмена сообщениями choice — это блок с несколькими источниками и одной целью, который представляет взаимодействие потока управления с набором источников.A choice messaging block is a multi-source, single-target block that represents a control-flow interaction with a set of sources. Блок choice будет ожидать доступа к любому из нескольких источников для создания сообщения и распространит индекс источника, создавшего сообщение.The choice block will wait for any one of multiple sources to produce a message and will propagate the index of the source that produced the message.

СинтаксисSyntax

template<
    class T
>
class choice: public ISource<size_t>;

ПараметрыParameters

TT
tupleТип на основе, представляющий полезные данные источников входных данных.A tuple-based type representing the payloads of the input sources.

ЭлементыMembers

Общедоступные определения типовPublic Typedefs

ИмяName ОписаниеDescription
type Псевдоним типа для T .A type alias for T.

Открытые конструкторыPublic Constructors

nameName ОписаниеDescription
choicechoice Перегружен.Overloaded. Создает блок обмена сообщениями choice .Constructs a choice messaging block.
Деструктор выбора ~~choice Destructor Уничтожает choice блок обмена сообщениями.Destroys the choice messaging block.

Открытые методыPublic Methods

nameName ОписаниеDescription
гласитaccept Принимает сообщение, которое было предложено этим choice блоком, передавая владение вызывающему объекту.Accepts a message that was offered by this choice block, transferring ownership to the caller.
acquire_refacquire_ref Получает счетчик ссылок choice для этого блока обмена сообщениями, чтобы предотвратить удаление.Acquires a reference count on this choice messaging block, to prevent deletion.
потребляющиеconsume Использует сообщение, которое было ранее предложено этим choice блоком обмена сообщениями и успешно зарезервировано целевым объектом, передавая владение вызывающему объекту.Consumes a message previously offered by this choice messaging block and successfully reserved by the target, transferring ownership to the caller.
has_valuehas_value Проверяет choice , инициализирован ли этот блок обмена сообщениями со значением.Checks whether this choice messaging block has been initialized with a value yet.
indexindex Возвращает индекс в, tuple представляющий элемент, выбранный choice блоком обмена сообщениями.Returns an index into the tuple representing the element selected by the choice messaging block.
link_targetlink_target Связывает целевой блок с этим choice блоком обмена сообщениями.Links a target block to this choice messaging block.
отпусканииrelease Освобождает предыдущее успешное резервирование сообщения.Releases a previous successful message reservation.
release_refrelease_ref Освобождает счетчик ссылок в этом choice блоке обмена сообщениями.Releases a reference count on this choice messaging block.
предназначенreserve Резервирует сообщение, которое было ранее предложено этим choice блоком обмена сообщениями.Reserves a message previously offered by this choice messaging block.
unlink_targetunlink_target Отменяет связь целевого блока с этим choice блоком обмена сообщениями.Unlinks a target block from this choice messaging block.
unlink_targetsunlink_targets Отменяет связь со всеми целевыми объектами из этого choice блока обмена сообщениями.Unlinks all targets from this choice messaging block. (Переопределяет метод ISource:: unlink_targets.)(Overrides ISource::unlink_targets.)
valuevalue Возвращает сообщение, чей индекс был выбран choice блоком обмена сообщениями.Gets the message whose index was selected by the choice messaging block.

КомментарииRemarks

Блок Choice гарантирует, что будет использоваться только одно из входящих сообщений.The choice block ensures that only one of the incoming messages is consumed.

Дополнительные сведения см. в разделе асинхронные блоки сообщений.For more information, see Asynchronous Message Blocks.

Иерархия наследованияInheritance Hierarchy

ISourceISource

choice

ТребованияRequirements

Заголовок: agents.hHeader: agents.h

Пространство имен: параллелизмNamespace: concurrency

гласитaccept

Принимает сообщение, которое было предложено этим choice блоком, передавая владение вызывающему объекту.Accepts a message that was offered by this choice block, transferring ownership to the caller.

virtual message<size_t>* accept(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_MsgId_MsgId
runtime_object_identityОбъект предлагаемого message объекта.The runtime_object_identity of the offered message object.

_PTarget_PTarget
Указатель на целевой блок, вызывающий accept метод.A pointer to the target block that is calling the accept method.

Возвращаемое значениеReturn Value

Указатель на сообщение о том, что вызывающий объект теперь является владельцем.A pointer to the message that the caller now has ownership of.

acquire_refacquire_ref

Получает счетчик ссылок choice для этого блока обмена сообщениями, чтобы предотвратить удаление.Acquires a reference count on this choice messaging block, to prevent deletion.

virtual void acquire_ref(_Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_PTarget_PTarget
Указатель на целевой блок, вызывающий этот метод.A pointer to the target block that is calling this method.

КомментарииRemarks

Этот метод вызывается ITarget объектом, который связан с этим источником во время выполнения link_target метода.This method is called by an ITarget object that is being linked to this source during the link_target method.

усмотрениchoice

Создает блок обмена сообщениями choice .Constructs a choice messaging block.

explicit choice(
    T _Tuple);

choice(
    Scheduler& _PScheduler,
    T _Tuple);

choice(
    ScheduleGroup& _PScheduleGroup,
    T _Tuple);

choice(
    choice&& _Choice);

ПараметрыParameters

_Tuple_Tuple
Объект tuple источников по выбору.A tuple of sources for the choice.

_PScheduler_PScheduler
Объект Scheduler , в котором запланирована задача распространения для блока обмена сообщениями choice .The Scheduler object within which the propagation task for the choice messaging block is scheduled.

_PScheduleGroup_PScheduleGroup
Объект ScheduleGroup , в котором запланирована задача распространения для блока обмена сообщениями choice .The ScheduleGroup object within which the propagation task for the choice messaging block is scheduled. Используемый объект Scheduler подразумевается группой расписаний.The Scheduler object used is implied by the schedule group.

_Choice_Choice
Блок обмена сообщениями choice , из которого выполняется копирование.A choice messaging block to copy from. Обратите внимание, что исходный объект становится потерянным, превращая этот конструктор в конструктор перемещения.Note that the original object is orphaned, making this a move constructor.

КомментарииRemarks

Среда выполнения использует планировщик по умолчанию, если вы не указали параметры _PScheduler или _PScheduleGroup .The runtime uses the default scheduler if you do not specify the _PScheduler or _PScheduleGroup parameters.

Конструкция перемещения не выполняется при блокировке. Это означает, что пользователь должен убедиться в отсутствии простых задач во время перемещения.Move construction is not performed under a lock, which means that it is up to the user to make sure that there are no light-weight tasks in flight at the time of moving. В противном случае могут возникнуть многочисленные гонки, приводящие к исключениям или недопустимому состоянию.Otherwise, numerous races can occur, leading to exceptions or inconsistent state.

~ Choice~choice

Уничтожает choice блок обмена сообщениями.Destroys the choice messaging block.

~choice();

потребляющиеconsume

Использует сообщение, которое было ранее предложено этим choice блоком обмена сообщениями и успешно зарезервировано целевым объектом, передавая владение вызывающему объекту.Consumes a message previously offered by this choice messaging block and successfully reserved by the target, transferring ownership to the caller.

virtual message<size_t>* consume(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_MsgId_MsgId
runtime_object_identityОбъект зарезервированного message объекта.The runtime_object_identity of the reserved message object.

_PTarget_PTarget
Указатель на целевой блок, вызывающий consume метод.A pointer to the target block that is calling the consume method.

Возвращаемое значениеReturn Value

Указатель на message объект, владельцем которого стал вызывающий объект.A pointer to the message object that the caller now has ownership of.

КомментарииRemarks

consumeМетод аналогичен accept , но ему всегда должен предшествовать вызов reserve , который возвращает true .The consume method is similar to accept, but must always be preceded by a call to reserve that returned true.

has_valuehas_value

Проверяет choice , инициализирован ли этот блок обмена сообщениями со значением.Checks whether this choice messaging block has been initialized with a value yet.

bool has_value() const;

Возвращаемое значениеReturn Value

true , если блок получил значение; false в противном случае —.true if the block has received a value, false otherwise.

номерindex

Возвращает индекс в, tuple представляющий элемент, выбранный choice блоком обмена сообщениями.Returns an index into the tuple representing the element selected by the choice messaging block.

size_t index();

Возвращаемое значениеReturn Value

Индекс сообщения.The message index.

КомментарииRemarks

Полезные данные сообщения можно извлечь с помощью get метода.The message payload can be extracted using the get method.

Связывает целевой блок с этим choice блоком обмена сообщениями.Links a target block to this choice messaging block.

virtual void link_target(_Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_PTarget_PTarget
Указатель на ITarget блок, связываемый с этим choice блоком обмена сообщениями.A pointer to an ITarget block to link to this choice messaging block.

отпусканииrelease

Освобождает предыдущее успешное резервирование сообщения.Releases a previous successful message reservation.

virtual void release(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_MsgId_MsgId
runtime_object_identity message Объект для освобожденного объекта.The runtime_object_identity of the message object being released.

_PTarget_PTarget
Указатель на целевой блок, вызывающий release метод.A pointer to the target block that is calling the release method.

release_refrelease_ref

Освобождает счетчик ссылок в этом choice блоке обмена сообщениями.Releases a reference count on this choice messaging block.

virtual void release_ref(_Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_PTarget_PTarget
Указатель на целевой блок, вызывающий этот метод.A pointer to the target block that is calling this method.

КомментарииRemarks

Этот метод вызывается ITarget объектом, для которого удаляется связь из этого источника.This method is called by an ITarget object that is being unlinked from this source. Блоку источника разрешено освобождать все ресурсы, зарезервированные для целевого блока.The source block is allowed to release any resources reserved for the target block.

предназначенreserve

Резервирует сообщение, которое было ранее предложено этим choice блоком обмена сообщениями.Reserves a message previously offered by this choice messaging block.

virtual bool reserve(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_MsgId_MsgId
runtime_object_identity message Объект для резервируемого объекта.The runtime_object_identity of the message object being reserved.

_PTarget_PTarget
Указатель на целевой блок, вызывающий reserve метод.A pointer to the target block that is calling the reserve method.

Возвращаемое значениеReturn Value

true значение, если сообщение было успешно зарезервировано, false в противном случае.true if the message was successfully reserved, false otherwise. Резервирования могут завершаться неудачей по ряду причин, включая следующие: сообщение уже было зарезервировано или принято другим целевым объектом, источник может отклонять резервирования и т. п.Reservations can fail for many reasons, including: the message was already reserved or accepted by another target, the source could deny reservations, and so forth.

КомментарииRemarks

После вызова метода reserve , если он выполняется, необходимо вызвать метод consume или release , чтобы получить или предоставить владение сообщениями соответственно.After you call reserve, if it succeeds, you must call either consume or release in order to take or give up possession of the message, respectively.

Отменяет связь целевого блока с этим choice блоком обмена сообщениями.Unlinks a target block from this choice messaging block.

virtual void unlink_target(_Inout_ ITarget<size_t>* _PTarget);

ПараметрыParameters

_PTarget_PTarget
Указатель на ITarget блок, который необходимо удалить из этого choice блока сообщений.A pointer to an ITarget block to unlink from this choice messaging block.

Отменяет связь со всеми целевыми объектами из этого choice блока обмена сообщениями.Unlinks all targets from this choice messaging block.

virtual void unlink_targets();

КомментарииRemarks

Этот метод не требуется вызывать из деструктора, так как деструктор для внутреннего single_assignment блока будет иметь правильную связь.This method does not need to be called from the destructor because destructor for the internal single_assignment block will unlink properly.

Значение value

Возвращает сообщение, чей индекс был выбран choice блоком обмена сообщениями.Gets the message whose index was selected by the choice messaging block.

template <
    typename _Payload_type
>
_Payload_type const& value();

ПараметрыParameters

_Payload_type_Payload_type
Тип полезных данных сообщения.The type of the message payload.

Возвращаемое значениеReturn Value

Полезные данные сообщения.The payload of the message.

КомментарииRemarks

Поскольку блок сообщений choice может принимать входные данные с различными типами полезной нагрузки, необходимо указать тип полезной нагрузки в момент извлечения.Because a choice messaging block can take inputs with different payload types, you must specify the type of the payload at the point of retrieval. Тип можно определить на основе результата index метода.You can determine the type based on the result of the index method.

См. также разделSee also

Пространство имен Concurrencyconcurrency Namespace
Класс joinjoin Class
Класс single_assignmentsingle_assignment Class