kStatus kPxBlock_Send	(	kPxBlock	block,
		kPxPort	port,
		kMsgSet	msg
	)

Sends a message on a specific port.

By default, the kPxPort EmitAsynchronousData property is set to kFALSE, meaning that messages can only be emitted synchronously. In this state, attempting to send a message outside the scope of a block's OnReceive handler will result in undefined behaviour. When the EmitAsynchronousData property is set to kTRUE, messages are delivered to the pipe asynchronously, enabling messages to be sent either inside or outside of a block's OnReceive handler.

Asynchronous messages are not processed during the current synchronous pipe execution sequence; instead, they are queued and processed in a future execution pass. (For the serial pipe, a synchronous execution sequence refers to the processing of messages exchanged between connected blocks within the same pipe; for the parallel pipe, it refers to the processing of messages exchanged between connected blocks within the same processing group.) As a result, the use of asynchronous messaging can alter the typical execution order of blocks within the pipe.

Asynchronous messages should not be sent before the pipe is ready to receive those messages. For blocks that generate asynchronous messages in response to input messages that they receive (e.g., blocks that combine multiple inputs to later produce a single output), the Send method can be safely called at any time after the first synchronous message has been received; no special consideration is required. However, for blocks that generate spontaneous asynchronous messages (e.g., blocks that generate output messages based on an internal timer), care should be taken to ensure that output messages are not sent before the block's Engage method has been invoked by the pipe environment. This can normally be accomplished by overriding the block's VOnEngage method, and deferring the start of any asynchronous threads to that method. (Side note: blocks that create threads must respect the pipe's thread priority/affinity configuration, which can be determined by calling kPxBlock_ThreadPriorityClass, kPxBlock_ThreadPriorityOffset, and kPxBlock_ThreadAffinity).

Asynchronous messages should never be sent after a block's VOnStop method has been called.

Parameters

block	Block object.
port	Port object.
msg	Output message object (ownership is transferred, irrespective of operation status).

Returns

Operation status.

See also

kPxPort_EnableAsynchronousData, kPxBlock_OnEngage