Class ErlMbox

Provides a simple mechanism for exchanging messages with Erlang processes or other instances of this class

Inheritance
System.Object
DisposableObject
ErlMbox
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object, System.Object)
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: NFX.Erlang
Assembly: NFX.Erlang.dll
Syntax
public class ErlMbox : DisposableObject, IDisposable
Remarks

Each mailbox is associated with a unique ErlPid that contains information necessary for delivery of messages. When sending messages to named processes or mailboxes, the sender pid is made available to the recipient of the message. When sending messages to other mailboxes, the recipient can only respond if the sender includes the pid as part of the message contents. The sender can determine his own pid by calling Self.

Mailboxes can be named, either at creation or later. Messages can be sent to named mailboxes and named Erlang processes without knowing the ErlPid that identifies the mailbox. This is neccessary in order to set up initial communication between parts of an application. Each mailbox can have at most one name.

Messages to remote nodes are externalized for transmission, and as a result the recipient receives a copy of the original C# object. To ensure consistent behaviour when messages are sent between local mailboxes, such messages are cloned before delivery.

Additionally, mailboxes can be linked in much the same way as Erlang processes. If a link is active when a mailbox is closed any linked Erlang processes or ErlMbox's will be sent an exit signal. As well, exit signals will be (eventually) sent if a mailbox goes out of scope and its Dispose method called. However due to the nature of finalization (i.e. C# makes no guarantees about when Dispose will be called) it is recommended that you always explicitly close mailboxes if you are using links instead of relying on finalization to notify other parties in a timely manner.

When retrieving messages from a mailbox that has received an exit signal, an NFX.Erlang.ErlExit exception will be raised. Note that the exception is queued in the mailbox along with other messages, and will not be raised until it reaches the head of the queue and is about to be retrieved

Properties

Empty

Return true if there are no messages waiting in the receive queue of this connection

Declaration
public bool Empty { get; }
Property Value
Type Description
System.Boolean

Handle

Queue not empty status notification handle

Declaration
public WaitHandle Handle { get; }
Property Value
Type Description
System.Threading.WaitHandle

MsgCount

Return the number of messages currently waiting in the receive queue of this connection

Declaration
public int MsgCount { get; }
Property Value
Type Description
System.Int32

Name

Get the registered name of this mailbox, or string.Empty if the mailbox doesn't have a registered name

Declaration
public ErlAtom Name { get; }
Property Value
Type Description
ErlAtom

Node

Declaration
public ErlLocalNode Node { get; }
Property Value
Type Description
ErlLocalNode

QueueActive

Declaration
public bool QueueActive { get; }
Property Value
Type Description
System.Boolean

Self

Get the Pid identifying associated with this mailbox

Declaration
public ErlPid Self { get; }
Property Value
Type Description
ErlPid

Methods

AsyncRPC(ErlAtom, ErlAtom, ErlAtom, ErlList, IErlObject, Nullable<ErlAtom>)

Send RPC call to a given node.

Declaration
public void AsyncRPC(ErlAtom node, ErlAtom mod, ErlAtom fun, ErlList args, IErlObject ioServer, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node

Destination node for this RPC call
ErlAtom mod

Module name to call
ErlAtom fun

Function name to call
ErlList args

Function arguments
IErlObject ioServer

Either a PID or an Atom containing registered I/O server's name.
System.Nullable<ErlAtom> remoteCookie

Remote cookie

AsyncRPC(ErlAtom, ErlAtom, ErlAtom, ErlList, Nullable<ErlAtom>)

Declaration
public void AsyncRPC(ErlAtom node, ErlAtom mod, ErlAtom fun, ErlList args, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
ErlAtom mod
ErlAtom fun
ErlList args
System.Nullable<ErlAtom> remoteCookie

AsyncRPC(ErlAtom, String, String, ErlList, ErlPid, Nullable<ErlAtom>)

Declaration
public void AsyncRPC(ErlAtom node, string mod, string fun, ErlList args, ErlPid ioServer, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
System.String mod
System.String fun
ErlList args
ErlPid ioServer
System.Nullable<ErlAtom> remoteCookie

AsyncRPC(ErlAtom, String, String, ErlList, Nullable<ErlAtom>)

Declaration
public void AsyncRPC(ErlAtom node, string mod, string fun, ErlList args, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
System.String mod
System.String fun
ErlList args
System.Nullable<ErlAtom> remoteCookie

Clear()

Declaration
public void Clear()

Dequeue(Int32)

Declaration
protected IQueable Dequeue(int timeout = -1)
Parameters
Type Name Description
System.Int32 timeout
Returns
Type Description
IQueable

Destructor()

Declaration
protected override void Destructor()
Overrides

Down(ErlRef, ErlPid, ErlAtom)

Declaration
public void Down(ErlRef eref, ErlPid pid, ErlAtom reason)
Parameters
Type Name Description
ErlRef eref
ErlPid pid
ErlAtom reason

Enqueue(IQueable)

Declaration
protected void Enqueue(IQueable data)
Parameters
Type Name Description
IQueable data

Equals(Object)

Determine if two mailboxes are equal

Declaration
public override bool Equals(object o)
Parameters
Type Name Description
System.Object o
Returns
Type Description
System.Boolean
Overrides
System.Object.Equals(System.Object)

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
System.Int32
Overrides
System.Object.GetHashCode()

Link(ErlPid)

Link to a remote mailbox or Erlang process. Links are idempotent, calling this method multiple times will not result in more than one link being created

Declaration
public void Link(ErlPid to)
Parameters
Type Name Description
ErlPid to
Remarks

If the remote process subsequently exits or the mailbox is closed, a subsequent attempt to retrieve a message through this mailbox will cause an {@link Exit Exit} exception to be raised. Similarly, if the sending mailbox is closed, the linked mailbox or process will receive an exit signal.

If the remote process cannot be reached in order to set the link, the exception is raised immediately.

OnMailboxMessage(IQueable)

Declaration
protected virtual bool OnMailboxMessage(IQueable msg)
Parameters
Type Name Description
IQueable msg
Returns
Type Description
System.Boolean

Receive(Int32)

Wait for a message to arrive for this mailbox. On timeout return null

Declaration
public IErlObject Receive(int timeout = -1)
Parameters
Type Name Description
System.Int32 timeout

Timeout time in milliseconds
Returns
Type Description
IErlObject

receiveBuf(Int32)

Wait for a message to arrive for this mailbox

Declaration
public ErlInputStream receiveBuf(int timeout)
Parameters
Type Name Description
System.Int32 timeout

time in milliseconds
Returns
Type Description
ErlInputStream

a stream representing the still-encoded body of the next message waiting in this mailbox, or null on timeout

ReceiveMatch(ErlPatternMatcher, Int32)

Receive a message and match it against a given pattern

Declaration
public Tuple<IErlObject, int> ReceiveMatch(ErlPatternMatcher pm, int timeoutMsec = -1)
Parameters
Type Name Description
ErlPatternMatcher pm

Patterns to match the message against
System.Int32 timeoutMsec

Timeout in milliseconds
Returns
Type Description
System.Tuple<IErlObject, System.Int32>

Return a tuple containing the received message and index of the pattern in the pm instance that was successfully matched. On timeout the 2nd element of the tuple is -2 and 1st element of the tuple is null. On unsuccessful match the second element of the tuple is -1

ReceiveMatch(IErlObject, Int32)

Receive a message and match it against a given pattern

Declaration
public Tuple<IErlObject, ErlVarBind> ReceiveMatch(IErlObject pattern, int timeoutMsec = -1)
Parameters
Type Name Description
IErlObject pattern

Pattern to match the message against
System.Int32 timeoutMsec

Timeout in milliseconds
Returns
Type Description
System.Tuple<IErlObject, ErlVarBind>

Return a tuple containing the received message and variable binding object. On timeout the first element of the tuple is null. On unsuccessful match the second element of the tuple is null

ReceiveRPC(Int32)

Declaration
public IErlObject ReceiveRPC(int timeout = -1)
Parameters
Type Name Description
System.Int32 timeout
Returns
Type Description
IErlObject

Register(ErlAtom)

Declaration
public bool Register(ErlAtom name)
Parameters
Type Name Description
ErlAtom name
Returns
Type Description
System.Boolean

Register(String)

Register a name for this mailbox. Registering a name for a mailbox enables others to send messages without knowing the ErlPid of the mailbox. A mailbox can have at most one name; if the mailbox already had a name, calling this method will supercede that name

Declaration
public bool Register(string name)
Parameters
Type Name Description
System.String name
Returns
Type Description
System.Boolean

true if the name was available, or false otherwise

RPC(ErlAtom, ErlAtom, ErlAtom, ErlList, Int32, Nullable<ErlAtom>)

Declaration
public IErlObject RPC(ErlAtom node, ErlAtom mod, ErlAtom fun, ErlList args, int timeout, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
ErlAtom mod
ErlAtom fun
ErlList args
System.Int32 timeout
System.Nullable<ErlAtom> remoteCookie
Returns
Type Description
IErlObject

RPC(ErlAtom, ErlAtom, ErlAtom, ErlList, Nullable<ErlAtom>)

Declaration
public IErlObject RPC(ErlAtom node, ErlAtom mod, ErlAtom fun, ErlList args, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
ErlAtom mod
ErlAtom fun
ErlList args
System.Nullable<ErlAtom> remoteCookie
Returns
Type Description
IErlObject

RPC(ErlAtom, String, String, ErlList, Int32, Nullable<ErlAtom>)

Declaration
public IErlObject RPC(ErlAtom node, string mod, string fun, ErlList args, int timeout, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
System.String mod
System.String fun
ErlList args
System.Int32 timeout
System.Nullable<ErlAtom> remoteCookie
Returns
Type Description
IErlObject

RPC(ErlAtom, String, String, ErlList, Nullable<ErlAtom>)

Declaration
public IErlObject RPC(ErlAtom node, string mod, string fun, ErlList args, ErlAtom? remoteCookie = default (ErlAtom? ))
Parameters
Type Name Description
ErlAtom node
System.String mod
System.String fun
ErlList args
System.Nullable<ErlAtom> remoteCookie
Returns
Type Description
IErlObject

RPCcast(ErlAtom, ErlAtom, ErlAtom, ErlList)

Declaration
public void RPCcast(ErlAtom node, ErlAtom mod, ErlAtom fun, ErlList args)
Parameters
Type Name Description
ErlAtom node
ErlAtom mod
ErlAtom fun
ErlList args

RPCcast(ErlAtom, ErlAtom, ErlAtom, ErlList, IErlObject)

Declaration
public void RPCcast(ErlAtom node, ErlAtom mod, ErlAtom fun, ErlList args, IErlObject ioServer)
Parameters
Type Name Description
ErlAtom node
ErlAtom mod
ErlAtom fun
ErlList args
IErlObject ioServer

Send(ErlAtom, ErlAtom, IErlObject)

Send a message to a named mailbox created from another node

Declaration
public bool Send(ErlAtom node, ErlAtom name, IErlObject msg)
Parameters
Type Name Description
ErlAtom node
ErlAtom name
IErlObject msg
Returns
Type Description
System.Boolean

Unlink(ErlPid)

Remove a link to a remote mailbox or Erlang process. This method removes a link created with ErlLink Links are idempotent; calling this method once will remove all links between this mailbox and the remote ErlPid

Declaration
public void Unlink(ErlPid to)
Parameters
Type Name Description
ErlPid to

Events

MailboxMessage

If this event is assigned, it will be called on arrival of a message, but the messages will not be put in the queue

Declaration
public event MailboxMsgEventHandler MailboxMessage
Event Type
Type Description
MailboxMsgEventHandler

Implements

System.IDisposable

Extension Methods