PCR Wiki & Documentation Rss Feed

UPDATED WIKI: FAQ

staceyw — Fri, 16 Mar 2007 16:39:19 GMT

PCR FAQ

UPDATED WIKI: What is a Selector?

staceyw — Fri, 16 Mar 2007 16:34:41 GMT

What is a Selector?

The best way to think about selectors is with an analogy. A selector is like a query on a collection of objects in a port. If the query matches, the item(s) are removed from the port and the selector is run asyncronously. Using this thinking, a port is the table, the port items are the rows, and a Selector is the SQL query.

UPDATED WIKI: Cool comments from devs

staceyw — Tue, 30 Jan 2007 16:51:49 GMT

Karloff wrote Mon at 5:33 PM delete this comment
Excellent work and a much needed alternative to CCR for the community who may not be able to utilize commercial licensing of the MS Robotics Runtime components. I look forward to giving the PCR a run. Keep up the fantastic job and thanks!

UPDATED WIKI: FAQ

staceyw — Tue, 30 Jan 2007 16:50:54 GMT

PCR FAQ

UPDATED WIKI: What is a Port?

staceyw — Tue, 30 Jan 2007 16:29:15 GMT

What is a Port?

A port is a container for objects of a type. A port also contains a collection of handlers that will be evaluated in-order when a new item is added to the port. So a port contains both items and selectors(1) as seperate lists. After adding an item, if a selector is satisfied, the matching item(s) are removed from the port and the selector is invoked with the item(s).

1) A Selector contains logic to pick one or more items from one or more ports.

UPDATED WIKI: FAQ

staceyw — Tue, 30 Jan 2007 16:21:05 GMT

PCR FAQ

UPDATED WIKI: Home

staceyw — Tue, 30 Jan 2007 16:20:24 GMT

What is PCR?

Port Concurrency Runtime (PCR) is a Port-Based asyncronous message passing library.

Simply put, you push messages to ports and the messages are processed (i.e popped) asyncronously using handlers which we call Selectors. All messages (i.e. objects) are sent and received via a Port. Selectors are user defined message handlers that can atomically process a single message or multiple messages from one or more ports based on rules defined by the Selector. The library includes common selectors that should satisfy the most common patterns such as SelectOne, SelectMany, Choice, Interleave, and Join.

        /// <summary>
        /// Test single item selector. SelectOne "can" have a FIFO gaureentee (depending on other factors defined by usage). In this case, only one
        /// selector will be scheduled at a time, but can also be set to run concurrent. The selector will run again when a message is pushed on port.
        /// </summary>
        static void SelectOneTest()
        {
            // Create a port and add some items.
            Port<string> p = new Port<string>();
            for (int i = 0; i < 20; i++)
                p.Push(i.ToString("00"));
            int activeCount = 0;
 
            // Create and activate the selector.
            Selector.SelectOne<string>(true, p,
                delegate(string s)
                {
                    if ( Interlocked.Increment(ref activeCount) > 1 )
                        Console.WriteLine("Error: active count should never go above 1.");
                    Console.WriteLine("SelectOneTest: {0} ThreadID:{1:00} Active:{2}", s, Thread.CurrentThread.ManagedThreadId, activeCount);
                    Thread.Sleep(10);
                    Interlocked.Decrement(ref activeCount);
                }).Add(); 
        }

The above code shows the general pattern that will be used by all selectors. A port is created, messages are added, and we register a selector query to process messages when they arrive on the port. The PCR runtime handles invoking the selector(s) registered with the port based on the selector rules and message availability. So a selector could run right away or not at all. More complex patterns such as selecting from many ports (i.e. a Join) or selecting many messages from a single port follow the same pattern. Things like Where filters are as simple as supplying a predicate delegate to a selector.

Helpful Links

--
William Stacey [C# MVP]

UPDATED WIKI: When is port processed FIFO or not?

staceyw — Tue, 30 Jan 2007 08:46:05 GMT

When are Port items processed in FIFO order?

By itself, a Port has FIFO queue symantics. Items are added at the end of the port and retrieved from the start of the port. However, Selectors can change this.

A Port is FIFO when:

A Selector's concurrent flag set to false. Another handler will not be scheduled until the current handler completes.
No other selectors are attached to the port. Another selector may also grab items from the port. Therefore, in the context of each selector, items could seem to be missing.
No filter (i.e. a Where predicate) is used. A filter explicitly nullifies the FIFO contract because it can grab items out of order.

A Port is not FIFO when:

A Selector's concurrent flag set to true. This would allow multiple items to be scheduled concurrently. The order of execution is not defined by the OS scheduler.
Multiple selectors are attached to the same port. Selectors would compete for items and the order of execution would be undefined.
A filter is used. A Selector filter, by design, allows for out-of-order processing of items.

UPDATED WIKI: When is port processed FIFO or not?

staceyw — Tue, 30 Jan 2007 08:45:40 GMT

A Port is FIFO when:

A Selector's concurrent flag set to false. Another handler will not be scheduled until the current handler completes.
No other selectors are attached to the port. Another selector may also grab items from the port. Therefore, in the context of each selector, items could seem to be missing.
No filter (i.e. a Where predicate) is used. A filter explicitly nullifies the FIFO contract because it can grab items out of order.

A Port is not FIFO when:

A Selector's concurrent flag set to true. This would allow multiple items to be scheduled concurrently. The order of execution is not defined by the OS scheduler.
Multiple selectors are attached to the same port. Selectors would compete for items and the order of execution would be undefined.
A filter is used. A Selector filter, by design, allows for out-of-order processing of items.

UPDATED WIKI: When is port processed FIFO or not?

staceyw — Tue, 30 Jan 2007 08:45:23 GMT

When are Port items processed in FIFO order?

By itself a Port has FIFO queue symantics. Items are added at the end of the port and retrieved from the start of the port. However, Selectors can change this.

A Port is FIFO when:

A Selector's concurrent flag set to false. Another handler will not be scheduled until the current handler completes.
No other selectors are attached to the port. Another selector may also grab items from the port. Therefore, in the context of each selector, items could seem to be missing.
No filter (i.e. a Where predicate) is used. A filter explicitly nullifies the FIFO contract because it can grab items out of order.

A Port is not FIFO when:

A Selector's concurrent flag set to true. This would allow multiple items to be scheduled concurrently. The order of execution is not defined by the OS scheduler.
Multiple selectors are attached to the same port. Selectors would compete for items and the order of execution would be undefined.
A filter is used. A Selector filter, by design, allows for out-of-order processing of items.

UPDATED WIKI: When is port processed FIFO or not?

staceyw — Tue, 30 Jan 2007 08:45:03 GMT

When are Port items processed FIFO?

By itself a Port has FIFO queue symantics. Items are added at the end of the port and retrieved from the start of the port. However, Selectors can change this.

A Port is FIFO when:

A Selector's concurrent flag set to false. Another handler will not be scheduled until the current handler completes.
No other selectors are attached to the port. Another selector may also grab items from the port. Therefore, in the context of each selector, items could seem to be missing.
No filter (i.e. a Where predicate) is used. A filter explicitly nullifies the FIFO contract because it can grab items out of order.

A Port is not FIFO when:

A Selector's concurrent flag set to true. This would allow multiple items to be scheduled concurrently. The order of execution is not defined by the OS scheduler.
Multiple selectors are attached to the same port. Selectors would compete for items and the order of execution would be undefined.
A filter is used. A Selector filter, by design, allows for out-of-order processing of items.

UPDATED WIKI: When is port processed FIFO or not?

staceyw — Tue, 30 Jan 2007 08:44:37 GMT

When is Port processed FIFO or not?

By itself a Port has FIFO queue symantics. Items are added at the end of the port and retrieved from the start of the port. However, Selectors can change this.

A Port is FIFO when:

A Selector's concurrent flag set to false. Another handler will not be scheduled until the current handler completes.
No other selectors are attached to the port. Another selector may also grab items from the port. Therefore, in the context of each selector, items could seem to be missing.
No filter (i.e. a Where predicate) is used. A filter explicitly nullifies the FIFO contract because it can grab items out of order.

A Port is not FIFO when:

A Selector's concurrent flag set to true. This would allow multiple items to be scheduled concurrently. The order of execution is not defined by the OS scheduler.
Multiple selectors are attached to the same port. Selectors would compete for items and the order of execution would be undefined.
A filter is used. A Selector filter, by design, allows for out-of-order processing of items.

UPDATED WIKI: When is port processed FIFO or not?

staceyw — Tue, 30 Jan 2007 08:35:09 GMT

A Port is FIFO when:

Selector concurrent flag set to false. Another item will not be scheduled until first one completes.
No other selectors attached to port. Another selector may also grab items from the port. So in the context of each selector, items would be missing.
No filter (i.e. Where) used. A filter explicitly nullifies the fifo contract because it can grap items out of order based on what item in the port matches.

a Port is Not FIFO when:

The Selector concurrent flag set to true. This would allow multiple items to be scheduled concurrently. The order of execution is not defined by the OS scheduler.
Multiple selectors are attached to the same port. Selectors would compete for items and the order of execution would be undefined.
A filter is used. A filter allows out-of-order processing of items by design.

UPDATED WIKI: Can I do recursion?

staceyw — Sun, 28 Jan 2007 19:34:37 GMT

Can I do recursion with Ports?

Sure. This is more an inherent ability of the loose nature of ports. You can keep posting messages to ports from anywhere in your program, so you can get interesting and powerful recursion abilities. Here is a TreeWalk sample that demonstrates this:

        /// <summary>
        /// Note how easy it is to do recursion. Because this uses stack-less recursion we don't have to
        /// worry about stack overflow. However, we now have a different challenge - "How do we ever know
        /// when we are actually complete because there is no stack to unwind?"
        /// </summary>
        private static void TreeWalk()
        {
		    
            Port<DirectoryInfo> dirPort = new Port<DirectoryInfo>();
            Port<FileInfo> filesPort = new Port<FileInfo>();
 
            DirectoryInfo root = new DirectoryInfo(@"c:\windows");
            if (!root.Exists)
            {
                Console.WriteLine("Root does not exist.");
                return;
            }
            dirPort.Push(root);    // Start at c:\temp.
 
            long folders = 0;
            Selector.SelectOne(true, dirPort,
                delegate(DirectoryInfo di)
                {
                    foreach (FileInfo fi in di.GetFiles())
                        filesPort.Push(fi);
                    foreach (DirectoryInfo di2 in di.GetDirectories())
                    {
                        folders++;
                        dirPort.Push(di2);
                    }
                }).Add();
 
            long totSize = 0;
            long files = 0;
            Console.WriteLine("Files in tree:");
            Selector.SelectOne(true, filesPort,
                delegate(FileInfo fi)
                {
                    files++;
                    totSize += fi.Length;
                    Console.WriteLine(fi.FullName);
                }).Add();
 
            // Output.
            Thread.Sleep(2000); // Guess we are complete by now. How to tell when done?
            Console.WriteLine("Size    :  {0:n0} bytes.", totSize);
            Console.WriteLine("Contains:  {0:n0} Files, {1:n0} Folders.", files, folders);
        }

Also see WikiPedia on Recursion
--
William

UPDATED WIKI: How is this similar to events?

staceyw — Sun, 28 Jan 2007 19:33:18 GMT

How is this similar to events?

Actually, that is one way to think about the PCR. You could actually replace events with Ports. An event has a delegate with some signature that is called by some producer code. In a similar way, you can register handlers with a port. When an object is added to a port, the registered handlers (i.e. selectors) are evaluated to determine a match. If a match, the selector is run on a thread pool thread.

There are also some fundemental differences:

You don't explicity call handlers in the PCR, you just post messages on a Port which is a non-blocking operation. The port will queue the item and will schedule a matching selector to run the handler.
Selectors are automatically scheduled on the thread pool, not run in the context of the producer.
Ports provide a clean and clear seperation between data and code that operates on that data. The port becomes the interface, and you just pass messages between any number of services just by having a reference to a port. This allows very loose coupling between layers and/or services within an application.
Selectors can have many forms of arbitration associated with them. Selectors can be joined together, they can return one to many items, they can have attached filters, etc. In a sense, this is a form of event overloading.

UPDATED WIKI: Can I update UI with PCR?

staceyw — Sun, 28 Jan 2007 19:32:59 GMT

Can update UI with the PCR?

Good question. This is such a common need that we implemented it.
Actually, it was pretty easy and we did not have to special case the selectors. We derived another dispatch queue class from DispatchQueueBase that is UI specific (i.e. UIDispatchQueue). So instead of queuing work to a thread pool, we directly queue the work items on the windows message queue. The cool part is you can use selector arbitration as normal, so you can do things like wait on multiple items for performance reasons or other. You can see an example of this in the GuiProgress form in the PcrChat project. Below is the code (there is a smaller sample at end of page):

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using Wjs.Pcr;
using System.Threading;
 
namespace PcrChat
{
    public partial class GuiProgress : Form
    {
        private Port<WorkStatus> progressPort = new Port<WorkStatus>();
        private volatile bool cancel;
 
        public GuiProgress()
        {
            InitializeComponent();
            InitProgress();
        }
 
        private void StartWorker(string path)
        {
            // Note, we have no gui logic in our worker. This keeps it loosely coupled from UI.
            // We could also use an Interleave here.
            Port<string> wp = new Port<string>();
            wp.Push(path);
            Selector.SelectOne(true, wp,
                delegate(string name)
                {
                    for (int i = 1; i <= 100; i++)
                    {
                        if (this.cancel)
                        {
                            this.progressPort.Push(new WorkStatus(name, -1));
                            return;
                        }
                        Thread.Sleep(30);   // Sim work.
                        progressPort.Push(new WorkStatus(name, i));
                    }
                }).Add();
        }
 
        private void InitProgress()
        {
            // The progress selector has the UI knowledge.
            // Note we are not using any BeginInvokes, events, monitors, or pulses; just
            // plain message passing. This should ultimately simplify your code.
            Selector.SelectOne(true, progressPort,
                delegate(WorkStatus ws)
                {
                    // We are running on the UI thread here so take care not to do blocking calls.
                    if (ws.Value == -1)
                    {
                        Console.WriteLine("Worker cancelled.");
                        Reset();
                        return;
                    }
                    if (ws.Name == "Work1")
                        this.progressBar1.Value = ws.Value;
                    else
                        this.progressBar2.Value = ws.Value;
                    if (this.progressBar1.Value == 100 && this.progressBar2.Value == 100)
                    {
                        MessageBox.Show("Complete");
                        Reset();
                    }
                }).Add(new UIDispatchQueue(this)); // Note use of UIDispatchQueue.
        }
 
        private void btnStartWork_Click(object sender, EventArgs e)
        {
            // Start two workers.
            this.btnStartWork.Enabled = false;
            StartWorker("Work1");
            StartWorker("Work2");
            this.btnCancel.Enabled = true;
        }
 
        private void Reset()
        {
            this.progressBar1.Value = 0;
            this.progressBar2.Value = 0;
            this.progressBar1.Style = ProgressBarStyle.Blocks;
            this.progressBar2.Style = ProgressBarStyle.Blocks;
            this.btnStartWork.Enabled = true;
            this.btnCancel.Enabled = false;
            this.cancel = false;
        }
 
        private void btnCancel_Click(object sender, EventArgs e)
        {
            this.btnCancel.Enabled = false;
            this.cancel = true;
        }
    }
 
    internal class WorkStatus
    {
        public string Name;
        public int Value;
 
        public WorkStatus(string name, int value)
        {
            this.Name = name;
            this.Value = value;
        }
    }
}

Here is simple console sample that demos the general idea without all the UI stuff in the way:

        private static void UITest2()
        {
            // Do some work on worker thread(s), then post results back to UI thread.
            // In this case, our UI is console, but same idea applies.
 
            Port<int> uiPort = new Port<int>();
            Port<int> workerPort = new Port<int>();
 
            // This handler does async wait for work. No blocked threads.
            Selector.SelectOne(true, true, workerPort,
                delegate(int i)
                {
                    // I am doing some work on a TP thread.
                    i = i + 2;
                    uiPort.Push(i); // Post results to UI.
                }).Add();
 
            // This handler does async wait for UI result. Again, no blocked threads or polling.
            Selector.SelectOne(true, true, uiPort,
                delegate(int i)
                {
                    // Update Form control, etc.
                    Console.WriteLine("UI: " + i);
                }).Add(new UIDispatchQueue());
 
            // Post some work tasks. Can be called from any thread.
            workerPort.Push(1);
            workerPort.Push(2);
        }

-- William

UPDATED WIKI: Is there a Mono port?

staceyw — Sun, 28 Jan 2007 19:32:35 GMT

Is there a Mono port?

Not yet, but would like one. Care to help?

UPDATED WIKI: When did the PCR become self aware?

staceyw — Sun, 28 Jan 2007 19:31:23 GMT

When did the PCR become self aware?

Sunday, January 07, 2007 3:41:48:12.69 AM Zulu

UPDATED WIKI: Can I do recursion?

staceyw — Fri, 26 Jan 2007 18:38:42 GMT

Sure. This is more an inherent ability of the loose nature of ports. You can keep posting messages to ports from anywhere in your program, so you can get interesting and powerful recursion abilities. Here is a TreeWalk sample that demonstrates this:

        /// <summary>
        /// Note how easy it is to do recursion. Because this uses stack-less recursion we don't have to
        /// worry about stack overflow. However, we now have a different challenge - "How do we ever know
        /// when we are actually complete because there is no stack to unwind?"
        /// </summary>
        private static void TreeWalk()
        {
		    
            Port<DirectoryInfo> dirPort = new Port<DirectoryInfo>();
            Port<FileInfo> filesPort = new Port<FileInfo>();
 
            DirectoryInfo root = new DirectoryInfo(@"c:\windows");
            if (!root.Exists)
            {
                Console.WriteLine("Root does not exist.");
                return;
            }
            dirPort.Push(root);    // Start at c:\temp.
 
            long folders = 0;
            Selector.SelectOne(true, dirPort,
                delegate(DirectoryInfo di)
                {
                    foreach (FileInfo fi in di.GetFiles())
                        filesPort.Push(fi);
                    foreach (DirectoryInfo di2 in di.GetDirectories())
                    {
                        folders++;
                        dirPort.Push(di2);
                    }
                }).Add();
 
            long totSize = 0;
            long files = 0;
            Console.WriteLine("Files in tree:");
            Selector.SelectOne(true, filesPort,
                delegate(FileInfo fi)
                {
                    files++;
                    totSize += fi.Length;
                    Console.WriteLine(fi.FullName);
                }).Add();
 
            // Output.
            Thread.Sleep(2000); // Guess we are complete by now. How to tell when done?
            Console.WriteLine("Size    :  {0:n0} bytes.", totSize);
            Console.WriteLine("Contains:  {0:n0} Files, {1:n0} Folders.", files, folders);
        }

Also see WikiPedia on Recursion
--
William

UPDATED WIKI: FAQ

staceyw — Fri, 26 Jan 2007 18:35:49 GMT