The powershell queue collection

Today I want to quickly talk about the systems.collections.queue collection when working with powershell queues.

Why should we care about the system.collections.queue collection when working with powershell queues?

Working with powershell, generally a simple array declared and used like this will generally be enough.

 $array = @() $array += “Stéphane” $array += “van Gulick”

$array = @()

$array += “Stéphane”

$array += “van Gulick”

We then need to access our array via the index

 PS C:WINDOWSsystem32> $array[1] van Gulick

1 2	PS C:WINDOWSsystem32> $array[1] van Gulick

Although this is trivial, and very often enough for our daily business (or in other words, we will always find a way to make it work). there are sometime some other (better?) ways to do things.

The System.Collection.Queue is just like a regular array, but is has some additional convenient methods that allow us to always return the first element added to our queue.

The System.Collection.queue follows the principle of first in, first out.

Methods and properties you don’t want to miss when using the powershell queue (system.collections.queue):

Lets have a look at the members of our collection object:

 $q = New-Object System.Collections.Queue $q | gm # throws an error

1 2	$q = New-Object System.Collections.Queue $q \| gm # throws an error

Pretty surprisingly, when you try to look at the members that are available you will find your self in front of the following error:

 gm : You must specify an object for the Get-Member cmdlet. At line:1 char:6 + $q | gm # throws an error +      ~~ + CategoryInfo          : CloseError: (:) [Get-Member], InvalidOperationException + FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand

gm : You must specify an object for the Get-Member cmdlet.

At line:1 char:6

+ $q | gm # throws an error

+ ~~

+ CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException

+ FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand

I’ll explain a bit later what really happened here, but for now, know that although we have had this error message, and when we look into our $q variable it seems empty, the instance has been created. We can see all the members if we use the -inputObject parameter, as in the example below.

 PS C:WINDOWSsystem32> get-member -InputObject $q TypeName: System.Collections.Queue Name           MemberType Definition                                                                                                 —-           ———- ———-                                                                                                 Clear          Method     void Clear()                                                                                               Clone          Method     System.Object Clone(), System.Object ICloneable.Clone()                                                    Contains       Method     bool Contains(System.Object obj)                                                                           CopyTo         Method     void CopyTo(array array, int index), void ICollection.CopyTo(array array, int index)                       Dequeue        Method     System.Object Dequeue()                                                                                    Enqueue        Method     void Enqueue(System.Object obj)                                                                            Equals         Method     bool Equals(System.Object obj)                                                                             GetEnumerator  Method     System.Collections.IEnumerator GetEnumerator(), System.Collections.IEnumerator IEnumerable.GetEnumerator() GetHashCode    Method     int GetHashCode()                                                                                          GetType        Method     type GetType()                                                                                             Peek           Method     System.Object Peek()                                                                                       ToArray        Method     System.Object[] ToArray()                                                                                  ToString       Method     string ToString()                                                                                          TrimToSize     Method     void TrimToSize()                                                                                          Count          Property   int Count {get;}                                                                                           IsSynchronized Property   bool IsSynchronized {get;}                                                                                 SyncRoot       Property   System.Object SyncRoot {get;}

PS C:WINDOWSsystem32> get-member -InputObject $q

TypeName: System.Collections.Queue

Name MemberType Definition

——————— —————

ClearMethod void Clear()

Clone Method System.Object Clone(), System.Object ICloneable.Clone()

Contains Method bool Contains(System.Object obj)

CopyTo Method void CopyTo(array array, int index), void ICollection.CopyTo(array array, int index)

Dequeue Method System.Object Dequeue()

Enqueue Method void Enqueue(System.Object obj)

Equals Method bool Equals(System.Object obj)

GetEnumerator Method System.Collections.IEnumerator GetEnumerator(), System.Collections.IEnumerator IEnumerable.GetEnumerator()

GetHashCode Method int GetHashCode()

GetType Method type GetType()

Peek Method System.Object Peek()

ToArray Method System.Object[] ToArray()

ToString Method string ToString()

TrimToSize Method void TrimToSize()

CountPropertyint Count {get;}

IsSynchronized Propertybool IsSynchronized {get;}

SyncRoot Property System.Object SyncRoot {get;}

We will focus on the three most interesting ones of the Queue collection:

Enqueue
Dequeue
peek

The .Enqueue() method of the system.collections.Queue

The enqueue method is the method that will allow us to add new information to our powershell queue collection.

 $q.Enqueue(“hi”) $q.Enqueue(“How are”) $q.Enqueue(“you ?”) $q hi How are you ?

$q.Enqueue(“hi”)

$q.Enqueue(“How are”)

$q.Enqueue(“you ?”)

How are

you ?

Notice the order in which the strings are appearing.

Pretty straight forward I would say.

The DeQueue() method from powershell queue collection

The dequeue method is the method that will return the next element of our queue.

Remember, the systems.collections.Queue is a type of collection that respects the first in, First out principle

 PS C:WINDOWSsystem32> $q.Dequeue() hi

1 2	PS C:WINDOWSsystem32> $q.Dequeue() hi

In the example above, “hi” is the first element to be returned when we called the DeQueue() method.

When we look again in our variable, we can see that the value hi is not more present anymore, but “how are” and “you” are still there.

 PS C:WINDOWSsystem32> $q How are you ?

PS C:WINDOWSsystem32> $q

How are

you ?

The Peek() method:

The peek method will work exactly as the Dequeue() method, except, that the item that was returned will not be removed from the Queue. As it’s name suggest, it allows you to peek into the queue, and to see what would be the next returned element if you would call the DeQueue() method.

 PS C:WINDOWSsystem32> $q.Peek() How are

1 2	PS C:WINDOWSsystem32> $q.Peek() How are

You can see in the example above, the peek method (in red) returns the item, but doesn’t removes it from the stack collection.

Using the pop method, returns the “gulick” item just as the peek method informed us it would do, and in this case, removed it from the stack item.

A note about using queues in a multithreaded environment

As pointed out by Johan Akerstrom, queues are very interesting when using runspaces, as it helps to keep track of what has to come next. with Queues in a multithreaded environment (which runspaces are) you need to first create the Queue and then get a Synchronized Thread Safe wrapped Queue by calling the Synchronized() static method on the System.Collections.Queue class.