FSharp.Core


MailboxProcessor<'Msg> Type

A message-processing agent which executes an asynchronous computation.

The agent encapsulates a message queue that supports multiple-writers and a single reader agent. Writers send messages to the agent by using the Post method and its variations. The agent may wait for messages using the Receive or TryReceive methods or scan through all available messages using the Scan or TryScan method.

Constructors

Constructor Description

MailboxProcessor(body, ?cancellationToken)

Full Usage: MailboxProcessor(body, ?cancellationToken)

Parameters:
    body : MailboxProcessor<'Msg> -> Async<unit> - The function to produce an asynchronous computation that will be executed as the read loop for the MailboxProcessor when Start is called.
    ?cancellationToken : CancellationToken - An optional cancellation token for the body. Defaults to Async.DefaultCancellationToken.

Returns: MailboxProcessor<'Msg> The created MailboxProcessor.

Creates an agent. The body function is used to generate the asynchronous computation executed by the agent. This function is not executed until Start is called.

body : MailboxProcessor<'Msg> -> Async<unit>

The function to produce an asynchronous computation that will be executed as the read loop for the MailboxProcessor when Start is called.

?cancellationToken : CancellationToken

An optional cancellation token for the body. Defaults to Async.DefaultCancellationToken.

Returns: MailboxProcessor<'Msg>

The created MailboxProcessor.

Instance members

Instance member Description

this.CurrentQueueLength

Full Usage: this.CurrentQueueLength

Returns: int

Returns the number of unprocessed messages in the message queue of the agent.

Returns: int

this.DefaultTimeout

Full Usage: this.DefaultTimeout

Raises a timeout exception if a message not received in this amount of time. By default no timeout is used.

this.Error

Full Usage: this.Error

Returns: IEvent<Exception>

Occurs when the execution of the agent results in an exception.

Returns: IEvent<Exception>

this.Post

Full Usage: this.Post

Parameters:
    message : 'Msg - The message to post.

Posts a message to the message queue of the MailboxProcessor, asynchronously.

message : 'Msg

The message to post.

this.PostAndAsyncReply

Full Usage: this.PostAndAsyncReply

Parameters:
    buildMessage : AsyncReplyChannel<'Reply> -> 'Msg - The function to incorporate the AsyncReplyChannel into the message to be sent.
    ?timeout : int - An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Reply> An asynchronous computation that will wait for the reply from the agent.

Posts a message to an agent and await a reply on the channel, asynchronously.

The message is generated by applying buildMessage to a new reply channel to be incorporated into the message. The receiving agent must process this message and invoke the Reply method on this reply channel precisely once.

buildMessage : AsyncReplyChannel<'Reply> -> 'Msg

The function to incorporate the AsyncReplyChannel into the message to be sent.

?timeout : int

An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Reply>

An asynchronous computation that will wait for the reply from the agent.

this.PostAndReply

Full Usage: this.PostAndReply

Parameters:
    buildMessage : AsyncReplyChannel<'Reply> -> 'Msg - The function to incorporate the AsyncReplyChannel into the message to be sent.
    ?timeout : int - An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: 'Reply The reply from the agent.

Posts a message to an agent and await a reply on the channel, synchronously.

The message is generated by applying buildMessage to a new reply channel to be incorporated into the message. The receiving agent must process this message and invoke the Reply method on this reply channel precisely once.

buildMessage : AsyncReplyChannel<'Reply> -> 'Msg

The function to incorporate the AsyncReplyChannel into the message to be sent.

?timeout : int

An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: 'Reply

The reply from the agent.

this.PostAndTryAsyncReply

Full Usage: this.PostAndTryAsyncReply

Parameters:
    buildMessage : AsyncReplyChannel<'Reply> -> 'Msg - The function to incorporate the AsyncReplyChannel into the message to be sent.
    ?timeout : int - An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Reply option> An asynchronous computation that will return the reply or None if the timeout expires.

Like AsyncPostAndReply, but returns None if no reply within the timeout period.

buildMessage : AsyncReplyChannel<'Reply> -> 'Msg

The function to incorporate the AsyncReplyChannel into the message to be sent.

?timeout : int

An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Reply option>

An asynchronous computation that will return the reply or None if the timeout expires.

this.Receive

Full Usage: this.Receive

Parameters:
    ?timeout : int - An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Msg> An asynchronous computation that returns the received message.

Waits for a message. This will consume the first message in arrival order.

This method is for use within the body of the agent. This method is for use within the body of the agent. For each agent, at most one concurrent reader may be active, so no more than one concurrent call to Receive, TryReceive, Scan and/or TryScan may be active.

?timeout : int

An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Msg>

An asynchronous computation that returns the received message.

TimeoutException Thrown when the timeout is exceeded.

this.Scan

Full Usage: this.Scan

Parameters:
    scanner : 'Msg -> Async<'T> option - The function to return None if the message is to be skipped or Some if the message is to be processed and removed from the queue.
    ?timeout : int - An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'T> An asynchronous computation that scanner built off the read message.

Scans for a message by looking through messages in arrival order until scanner returns a Some value. Other messages remain in the queue.

Returns None if a timeout is given and the timeout is exceeded. This method is for use within the body of the agent. For each agent, at most one concurrent reader may be active, so no more than one concurrent call to Receive, TryReceive, Scan and/or TryScan may be active.

scanner : 'Msg -> Async<'T> option

The function to return None if the message is to be skipped or Some if the message is to be processed and removed from the queue.

?timeout : int

An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'T>

An asynchronous computation that scanner built off the read message.

TimeoutException Thrown when the timeout is exceeded.

this.Start

Full Usage: this.Start

Starts the agent.

this.TryPostAndReply

Full Usage: this.TryPostAndReply

Parameters:
    buildMessage : AsyncReplyChannel<'Reply> -> 'Msg - The function to incorporate the AsyncReplyChannel into the message to be sent.
    ?timeout : int - An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: 'Reply option The reply from the agent or None if the timeout expires.

Like PostAndReply, but returns None if no reply within the timeout period.

buildMessage : AsyncReplyChannel<'Reply> -> 'Msg

The function to incorporate the AsyncReplyChannel into the message to be sent.

?timeout : int

An optional timeout parameter (in milliseconds) to wait for a reply message. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: 'Reply option

The reply from the agent or None if the timeout expires.

this.TryReceive

Full Usage: this.TryReceive

Parameters:
    ?timeout : int - An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Msg option> An asynchronous computation that returns the received message or None if the timeout is exceeded.

Waits for a message. This will consume the first message in arrival order.

This method is for use within the body of the agent. Returns None if a timeout is given and the timeout is exceeded. This method is for use within the body of the agent. For each agent, at most one concurrent reader may be active, so no more than one concurrent call to Receive, TryReceive, Scan and/or TryScan may be active.

?timeout : int

An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'Msg option>

An asynchronous computation that returns the received message or None if the timeout is exceeded.

this.TryScan

Full Usage: this.TryScan

Parameters:
    scanner : 'Msg -> Async<'T> option - The function to return None if the message is to be skipped or Some if the message is to be processed and removed from the queue.
    ?timeout : int - An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'T option> An asynchronous computation that scanner built off the read message.

Scans for a message by looking through messages in arrival order until scanner returns a Some value. Other messages remain in the queue.

This method is for use within the body of the agent. For each agent, at most one concurrent reader may be active, so no more than one concurrent call to Receive, TryReceive, Scan and/or TryScan may be active.

scanner : 'Msg -> Async<'T> option

The function to return None if the message is to be skipped or Some if the message is to be processed and removed from the queue.

?timeout : int

An optional timeout in milliseconds. Defaults to -1 which corresponds to Timeout.Infinite.

Returns: Async<'T option>

An asynchronous computation that scanner built off the read message.

Static members

Static member Description

MailboxProcessor.Start(body, ?cancellationToken)

Full Usage: MailboxProcessor.Start(body, ?cancellationToken)

Parameters:
    body : MailboxProcessor<'Msg> -> Async<unit> - The function to produce an asynchronous computation that will be executed as the read loop for the MailboxProcessor when Start is called.
    ?cancellationToken : CancellationToken - An optional cancellation token for the body. Defaults to Async.DefaultCancellationToken.

Returns: MailboxProcessor<'Msg> The created MailboxProcessor.

Creates and starts an agent. The body function is used to generate the asynchronous computation executed by the agent.

body : MailboxProcessor<'Msg> -> Async<unit>

The function to produce an asynchronous computation that will be executed as the read loop for the MailboxProcessor when Start is called.

?cancellationToken : CancellationToken

An optional cancellation token for the body. Defaults to Async.DefaultCancellationToken.

Returns: MailboxProcessor<'Msg>

The created MailboxProcessor.