MailboxProcessor<'Msg> (FSharp.Core)

MailboxProcessor<'Msg> Type

Namespace: FSharp.Control
Assembly: FSharp.Core.dll
Base Type: obj
All Interfaces: IDisposable

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, isThrowExceptionAfterDisposed, ?cancellationToken)` Full Usage: `MailboxProcessor(body, isThrowExceptionAfterDisposed, ?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. isThrowExceptionAfterDisposed : `bool` - A flag denoting that an exception will be thrown when MailboxProcessor.Post is called after Control.MailboxProcessor has been disposed. ?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. isThrowExceptionAfterDisposed : `bool` A flag denoting that an exception will be thrown when MailboxProcessor.Post is called after Control.MailboxProcessor has been disposed. ?cancellationToken : `CancellationToken` An optional cancellation token for the `body`. Defaults to `Async.DefaultCancellationToken`. Returns: `MailboxProcessor<'Msg>` The created MailboxProcessor.
`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.Dispose

Full Usage: this.Dispose

Disposes the agent's internal resources.

Full Usage: this.Error

Returns: IEvent<Exception>

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

Returns: IEvent<Exception>

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.

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.

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.

Full Usage: this.Start

Starts the agent.


                
                  
                    
                      this.StartImmediate

Full Usage: this.StartImmediate

Starts the agent immediately on the current operating system thread.


                
                  
                    
                      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, isThrowExceptionAfterDisposed, ?cancellationToken)` Full Usage: `MailboxProcessor.Start(body, isThrowExceptionAfterDisposed, ?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. isThrowExceptionAfterDisposed : `bool` - A flag denoting that an exception will be thrown when MailboxProcessor.Post is called after Control.MailboxProcessor has been disposed. ?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. isThrowExceptionAfterDisposed : `bool` A flag denoting that an exception will be thrown when MailboxProcessor.Post is called after Control.MailboxProcessor has been disposed. ?cancellationToken : `CancellationToken` An optional cancellation token for the `body`. Defaults to `Async.DefaultCancellationToken`. Returns: `MailboxProcessor<'Msg>` The created MailboxProcessor.
`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.
`MailboxProcessor.StartImmediate(body, isThrowExceptionAfterDisposed, ?cancellationToken)` Full Usage: `MailboxProcessor.StartImmediate(body, isThrowExceptionAfterDisposed, ?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 StartImmediately is called. isThrowExceptionAfterDisposed : `bool` - A flag denotes will be thrown exception when MailboxProcessor.Post is called after Control.MailboxProcessor disposed. ?cancellationToken : `CancellationToken` - An optional cancellation token for the `body`. Defaults to `Async.DefaultCancellationToken`. Returns: `MailboxProcessor<'Msg>` The created MailboxProcessor.	Creates and starts an agent immediately on the current operating system thread. 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 StartImmediately is called. isThrowExceptionAfterDisposed : `bool` A flag denotes will be thrown exception when MailboxProcessor.Post is called after Control.MailboxProcessor disposed. ?cancellationToken : `CancellationToken` An optional cancellation token for the `body`. Defaults to `Async.DefaultCancellationToken`. Returns: `MailboxProcessor<'Msg>` The created MailboxProcessor.
`MailboxProcessor.StartImmediate(body, ?cancellationToken)` Full Usage: `MailboxProcessor.StartImmediate(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 StartImmediately 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 immediately on the current operating system thread. 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 StartImmediately is called. ?cancellationToken : `CancellationToken` An optional cancellation token for the `body`. Defaults to `Async.DefaultCancellationToken`. Returns: `MailboxProcessor<'Msg>` The created MailboxProcessor.