In this post, I assume that the reader is familiar with the algorithm and its inherent code size due to its frequent implementation with three distinct functions. I will begin by briefly describing a standard implementation of Minimax and then I will introduce a concise implementation using higher-order functions. Note that we will use Python and Haskell as pseudo-code.

Two-Player, Combinatorial Game Representation

We will begin with a simple description of two-player, combinatorial games abstractly. Games that can be categorized in this way include Checkers, Chess and Othello. However, we will focus on the abstraction of these games by representing their game state with a minimal interface necessary such that the Minimax algorithm can be applied to it. That is, the game should

• Provide a set of available moves given a specified game state,
• Obtain the next state of a game given a current state and move
• And determine whether the game is over.

Although it may be more coherent to use Python pseudo-code, Python does not have a syntax for interfaces; consequently, we will outline the interface using Haskell’s syntax for a typeclass.

class Game a
	get_available_moves :: a -> [Move]
	next_state :: a -> Move -> a
	is_gameover :: a -> Bool

Now that we know methods associated with a particular game state, we may access them as a standard method call in Python: game_state.get_available_moves(), game_state.next_state(move) and game_state.is_gameover().

Standard Implementation of Minimax

The standard implementation of the Minimax algorithm frequently includes three functions: minimax(game_state), min_play(game_state) and max_play(game_state). We will begin with the minimax(game_state) declaration. Note that I use Python here as working pseudo-code.

def minimax(game_state):
	moves = game_state.get_available_moves()
	best_move = moves[0]
	best_score = float('-inf')
	for move in moves:
		clone = game_state.next_state(move)
		score = min_play(clone)
		if score > best_score:
			best_move = move
			best_score = score
	return best_move

To summarize, Minimax is given a game state, obtains a set of valid moves from the game state, simulates all valid moves on clones of the game state, evaluates each game state which follows a valid move and finally returns the best move.

The following two helper functions simulate play between both the opposing player and the current player through the min_play and max_play procedures respectively. With the aid of these two helper functions, the entire game tree is traversed recursively given the current state of the game.

def min_play(game_state):
	if game_state.is_gameover():
		return eval(game_state)
	moves = game_state.get_available_moves()
	best_score = float('inf')
	for move in moves:
		clone = game_state.next_state(move)
		score = max_play(clone)
		if score < best_score:
			best_move = move
			best_score = score
	return best_score

def max_play(game_state):
	if game_state.is_gameover():
		return eval(game_state)
	moves = game_state.get_available_moves()
	best_score = float('-inf')
	for move in moves:
		clone = game_state.next_state(move)
		score = min_play(clone)
		if score > best_score:
			best_move = move
			best_score = score
	return best_score

In particular, the opponent intends to minimize the current player’s score and the current player intends to maximize their own score. Note that the helper functions short-circuit and return early if the game is over.

Notice that the scores are calculated through the eval(game_state) procedure. The implementation is omitted because it is dependent on the game itself; however, by convention, we say that the current player wins if the score is INF and loses if the score is -INF.

There are 35 lines (sans the blank newlines) in the current implementation of our algorithm. We will then reduce the number of lines by a factor of two using higher-order functions.

Concise Implementation of Minimax

It is intuitive that Minimax intends to find the maximum of a set of scores and a minimum of a set of scores for the current player and the opposing player respectively. Hence, it is intuitive to invest in the max() and min() procedures which function exactly as we need them to.

Let us begin by modifying the min_play(game_state) procedure.

First, the opposing player must check if the game is over and evaluate the game state if necessary.

def min_play(game_state):
	if game_state.is_gameover():
		return eval(game_state)

Second, the opposing player wants to return the minimum score of all of game states following valid moves.

def min_play(game_state):
	if game_state.is_gameover():
		return eval(game_state)
	return min(scores) # Incomplete

We know how to obtain the set of valid moves and we know how to obtain the next game state given a valid mode; however, we want to return the set the scores associated with the game states which follow valid moves. Subsequently, we must map() all of the game states which follow valid moves to a set of evaluations (or scores) that can be minimized.

def min_play(game_state):
	if game_state.is_gameover():
		return eval(game_state)
	return min(
		map(lambda move: max_play(game_state.next_state(move)),
			game_state.get_available_moves())

This procedure is now complete; however, I will briefly overview a few key points of this procedure. We begin with a lambda as the function which takes a game state and returns the evaluations of the state. Furthermore, we map() the set of game states which follow from valid moves to a set of evaluations that can be minimized.

The higher-order map(fn, list) function applies a function, over a domain of type \(A\) to a codomain of type \(B\), to a list of type \(A\):

$$fn : A \mapsto B$$

In our example, we map a list of game states to a list of evaluations.

Without loss of generality, the max_play() is similarly defined except that it uses the max() function for maximization. The further difficulty lies in the minimax() procedure which has the additional requirement of returning a valid move rather than a score alone.

To account for the additional requirement in the minimax() procedure, we modify the lambda of map() and the key of max() accordingly. That is, we begin by defining the lambda to be given a move and return a tuple containing (move, score). Furthermore, now that we have a tuple, we must decide which parameter to minimize over. We define this the key using the key keyword argument of max(). The final procedure is defined below:

def minimax(game_state):
	return max(
		map(lambda move: (move, min_play(game_state.next_state(move))), 
			game_state.get_available_moves()), 
		key = lambda x: x[1])

Now that all of the procedures have been redefined, we will see the final code:

def minimax(game_state):
	return max(
		map(lambda move: (move, min_play(game_state.next_state(move))), 
			game_state.get_available_moves()), 
		key = lambda x: x[1])

def min_play(game_state):
	if state.is_gameover():
		return .valuate(state)
	return min(
		map(lambda move: max_play(game_state.next_state(move)),
			game_state.get_available_moves()))

def max_play(game_state):
	if game_state.is_gameover():
		return evaluate(game_state)
	return max(
		map(lambda move: min_play(game_state.next_state(move)),
			game_state.get_available_moves()))

The total line count (sans the blank newlines) is 17. Without expanding the higher-order functions across several lines, there are 10 lines. In both accounts, the number of lines of code has been reduced by at least two-fold. For a working algorithm on an implementation of a game, see my Hexapawn GitHub repository.

Conclusion

It is easy to see that this implementation with higher-order functions is concise while maintaining readability of code (unlike our Perl friends in Code Golf). In general, several algorithms fit the problem that higher-order functions solve: composition of operations on larger data sets.

Focusing on the atomic components that an algorithm operates on such as elements of a set will not reduce the asymptotic lower-bound for the amount of code written. It is necessary that higher-level abstractions over such atomic elements exist to reduce the lower-bound for writing code. This notion has been explicated when the worst-case of sorting algorithms was reduced to less than \(O(nlgn)\) by using non-comparison-swap sorting algorithms. That is, sorting as simple comparison swap operations between two elements will never breach the \(O(nlgn)\) worst-case; however, Bucket sort has breached the worst-case by using operations outside of simple comparison and swap.

This particular implementation of Minimax could be reduced further into a single line of code using a fact that the Negamax variant of Minimax highlights for us:

I leave this as an exercise for the ambitious.

Motivation

A procedural style offers the same behavior as an OOP-style would; however, OOP makes optimal use of abstractions by providing common design patterns. Consequently, refactoring will be made possible.

Because this tutorial primarily regards the design of the resource manager, I will not provide implementation details beyond the header declarations; however, the full source can be found on my GitHub repository.

Linux Resource Limitation and Usage Specifications

Before designing a C++ wrapper, we must begin by noting some of the nuances in the Linux specification. In particular, the system calls associated with resource limitations and usage can be found in the Linux manual pages as getrlimit(), setrlimit() and getrusage(). The manual pages describe them as follows:

The getrlimit() and setrlimit() system calls get and set resource limits respectively. Each resource has an associated soft and hard limit, as defined by the rlimit structure.

getrusage() returns resource usage measures for who, which can be one of the following: RUSAGE_SELF, RUSAGE_CHILDREN, RUSAGE_THREAD. The resource usages are returned in the structure pointed to by usage.

Although these system calls are relatively straightforward, they also require a few constants and structures: rlimit and usage. The constants such as RLIMIT_CPU simply define the type of resource to limit; these constants can simply be referred to in the manual. The structures are defined as follows:

struct rlimit {
	rlim_t rlim_cur;  /* Soft limit */
	rlim_t rlim_max;  /* Hard limit (ceiling for rlim_cur) */
};

struct rusage {
	struct timeval ru_utime; /* user CPU time used */
	struct timeval ru_stime; /* system CPU time used */
	long   ru_maxrss;        /* maximum resident set size */
	long   ru_ixrss;         /* integral shared memory size */
	long   ru_idrss;         /* integral unshared data size */
	long   ru_isrss;         /* integral unshared stack size */
	long   ru_minflt;        /* page reclaims (soft page faults) */
	long   ru_majflt;        /* page faults (hard page faults) */
	long   ru_nswap;         /* swaps */
	long   ru_inblock;       /* block input operations */
	long   ru_oublock;       /* block output operations */
	long   ru_msgsnd;        /* IPC messages sent */
	long   ru_msgrcv;        /* IPC messages received */
	long   ru_nsignals;      /* signals received */
	long   ru_nvcsw;         /* voluntary context switches */
	long   ru_nivcsw;        /* involuntary context switches */
};

// necessary for struct rusage
struct timeval {
	time_t         tv_sec      /* seconds */
	suseconds_t    tv_usec     /* microseconds */
};

These structures can easily be transformed into classes. However, before we design the resource manager, let us describe the difference in programming styles that we expect.

Programming Styles

These structures along with the aforementioned system calls entails a procedural style of resource management. Consider the following procedural code:

struct rlimit cpu;
cpu.rlim_cur = 3;
cpu.rlim_max = 3;
setrlimit(RLIMIT_CPU, &cpu, NULL);

This takes quite a few lines that is often easily reduced to a single line by an OOP style:

ResourceManager.set_resource_limit(ResourceLimit(RLIMIT_CPU, 3, 3));

Although obviously longer as a single line, this does not logically conflict with an OOP programming paradigm. There is no performance optimization by changing the style to OOP; however, placing the code into a wrapper enables us to handle the code as a cross-cutting concern and therefore enable refactoring when the time comes. Recall that the primary benefit is making use of design patterns that OOP offers.

The Structural Design

Before we implement this wrapper, we must consider the high-level design. Allow us to begin with a driver program as our test case which will outline how we would like to use the interface. For simplicity, we will use main as our driver.

int main(int argc, char* argv[])
{
	// Acquire a single instance of the manager
	ResourceManager& manager = ResourceManager::instance();

	// Set resource limits
	manager.set_resource_limit(ResourceLimit(RLIMIT_CPU, 3, 3));
	manager.set_resource_limit(ResourceLimit(RLIMIT_RTTIME, 3, 3));
	manager.apply_limits();

	// Do some computation?
	fib(31);

	// Obtain a resource usage report
	ResourceUsage usage = manager.get_resource_usage(RUSAGE_SELF);

	// Print the resource usage report
	cout << "User Time (sec): " << usage.utime().seconds << endl;
	cout << "User Time (usec): " << usage.utime().microseconds << endl;
	cout << "System Time (sec): " << usage.stime().seconds << endl;
	cout << "System Time (usec): " << usage.stime().microseconds << endl;

	return 0;
}

Alright, so we have shown how we would like to use this interface. We will now consider the objects in use.

ResourceManager

Service that applies and tracks our resource limits.

ResourceLimit

Descriptor of a resource limit.

ResourceUsage

Descriptor of a resource usage report.

We must now consider a few nuances to our objects. First, we will look at the ResourceManager. In particular, it is only logical to have one, global instance of a ResourceManager because it applies to the entire process. Consequently, we should use the Singleton pattern. Further, because the manager tracks the currently applied resource limits and there exists a finite (and uniquely identifiable) set of resource limits, we will use a std::set data structure provided by STL.

The singleton design pattern ensures that only one instance of a class is instantiated throughout the lifetime of a program.

Since ResourceLimit and ResourceUsage are simply descriptors, it is easy enough to implement them as straightforward classes. Operationally, ResourceLimit should be able to apply() itself. ResourceUsage should be immutable because its data is consistently changing relative to the speed of our processor; consequently, it is not easily observable.

Now that we have outlined the structure, we will begin implementing the entire component.

Descriptor Design

We will begin with the obvious, descriptor implementation. Specifically, we will begin with the ResourceLimit implementation. The header file should proceed as follows:

#include "sys/resource.h"

class ResourceLimit
{
public:
	// constructors
	ResourceLimit(int);
	ResourceLimit(int, rlim_t, rlim_t);
	ResourceLimit(int, rlimit&);

	// accessors
	rlim_t soft_limit() const;
	rlim_t hard_limit() const;

	// native accessors
	const rlimit& to_rlimit() const;

	// operational functions
	void get_limit();
	void apply();

	// comparisons
	bool operator==(const ResourceLimit&) const;
	bool operator<(const ResourceLimit&) const;
private:
	int resource_id_;
	rlimit limit_;

	bool applied_;
};

As we can see, the necessary accessors are provided and the system-provided rlimit structure is hidden within the class. Further, the comparison operators are provided for when the class is used in the ResourceManager's set.

Before we begin designing the ResourceUsage class, we must define a structure to replace the system-provided timeval structure.

/**
 * An alternative representation of timevals
 */
class TimeParts
{
public:
	long seconds;
	long microseconds;

	// constructors
	TimeParts(long seconds, long microseconds) :
		seconds(seconds), microseconds(microseconds) {}

	TimeParts(timeval tv) :
		seconds(tv.tv_sec), microseconds(tv.tv_usec) {}
};

Now that we have redefined a class for timeval, we begin the ResourceUsage class which is, of course, immutable.

Immutable objects are non-modifiable after creation. They are necessary for implementing systems in which side effects are circumvented.

#include "sys/resource.h"
#include "sys/time.h"

/**
 * A descriptor of the resource usage of the
 * current process. This object is immutable
 * after construction.
 */
class ResourceUsage
{
public:
	// constructors
	ResourceUsage(int);
	
	// time accessors
	TimeParts utime() const;
	TimeParts stime() const;

	// accessors
	long maxrss() const;
	long ixrss() const;
	long idrss() const;
	long isrss() const;
	long minflt() const;
	long majflt() const;
	long nswap() const;
	long inblock() const;
	long oublock() const;
	long msgsnd() const;
	long msgrcv() const;
	long nsignals() const;
	long nvcsw() const;
	long nivcsw() const;
private:
	int who_;

	rusage usage_;
};

This descriptor also directly models the structure provided by the system; however, note that this design enables absolute immutability. With C-style structures, the data fields would be modifiable which is absolutely unnecessary.

Now that we have designed the descriptors, we can proceed with the design of the manager.

Resource Manager Design

We begin by noting that that the ResourceManager must obviously have access to the ResourceLimit and ResourceUsage descriptors and begin by including their headers into the source. Furthermore, we include the necessary resource management headers provided by the system and the set data structure provided by STL as we have intended.

#include "ResourceLimit.h"
#include "ResourceUsage.h"

#include "Singleton.h"

#include "sys/resource.h"
#include "sys/time.h"

#include <set>

Next, we design the manager to provide the same operational functionality that the Linux system-calls do; however, we design it in the context of sets of resource limits.

class ResourceManager
{
public:
	// mutators
	bool set_resource_limit(const ResourceLimit&);

	// accessors
	ResourceLimit get_resource_limit(int) const;
	ResourceUsage get_resource_usage(int) const;

	// operational functions
	void apply_limits();
private:
	std::set<ResourceLimit> resource_limits_;
};

This manager enables us to set defer resource limit application until necessary. Additionally, because we use a set data structure, no duplicate resource limits will overwrite each other. Now, we are only missing a single feature: the singleton.

Singleton Application

Although we can use the standard approach by manually embedding the operational functionality of a singleton into our ResourceManager, we can use a modern C++ idiom, the curiously recursive template pattern (CRTP). Specifically, the singleton will have a template parameter which will be our derived class. The singleton will then inject the singleton operational functionality into the derived class.

/**
 * Guarantees that only a single instance of an object will exist
 * throughout the lifetime of the program.
 */
template <class Derived>
class Singleton
{
public:
	Singleton(const Singleton&) = delete;
	Singleton& operator=(const Singleton&) = delete;

	static Derived& instance()
	{
		if (instance_ == nullptr)
			instance_ = new Derived();
		return *instance_;
	}
protected:
	Singleton() {}
	static Derived* instance_;
};

template <class Derived>
Derived* Singleton::instance_ = nullptr;

Here, notice that the singleton also uses some C++11 features where we delete the copy constructor and the copy assignment operator. Furthermore, notice that singleton operational functionality can now simply be inherited.

Finally, we can then inherit from our singleton,

class ResourceManager : public Singleton<ResourceManager>
{
public:
	// mutators
	bool set_resource_limit(const ResourceLimit&);

	// accessors
	ResourceLimit get_resource_limit(int) const;
	ResourceUsage get_resource_usage(int) const;

	// operational functions
	void apply_limits();
private:
	std::set<ResourceLimit> resource_limits_;
};

Note that it will be even easier to implement further singleton functionality if necessary; however, this component no further singletons.

At this point, our design is complete! Do not forget that the full source code is available in my GitHub repository.

Conclusion

It is easy to see that there was much duplication in the descriptor classes; however, it is a necessary evil to provide further constraints that classes provide such as immutability. Furthermore, use of the constructor enables quick initialization of objects as we have seen the driver.

Furthermore, utilizing OOP in C++ enables use of design patterns such as the singleton through CRTP. This allows us to design the resource manager as a cross-cutting concern and think of it as a logical abstraction rather than as an implementation detail.

Continuation

We will continue with our previous example which you can find on GitHub. It will be easier to follow along with the source code.

Beware that I will no longer provide a full example of the code. It is expected that you are aware of where the highlighted code modifications occur because the code file has grown large.

Structural Design

We begin by specifying the structural requirements of our chat. That is, we must specify the fields associated with our two primary data structures: User and ChatState.

User State Structure

We begin with the atomic data structure, the User. A user in a chat has a name.

private static class User {
	public String name;
	public User(String name) {
		this.name = name;
	}
}

Simple enough.

Chat State Structure

Next,the ChatState must model the configuration of a chat room: it should maintain the list of users currently in the chat.

private static class ChatState {
	private ArrayList<User> users;

	public ChatState() {}
}

Now to move on to the behaviors of our design.

Behavioral Design

The structure of our design has been outlined. Now we must enable interactions between these structures relative the possible events that may occur. Recall the events of a chat application:

User Arrival

Occurs when a user arrives to a room.

User Departure

Occurs when a user departs from a room.

User Message

Occurs when a user sends a message to a room.

Both the Chat and User must respond to these events accordingly. The following two sections will describe their behavioral implementation respectively.

Chat State Behaviors

Beginning with the ChatState this time, we must handle each of the aforementioned events. Specifically, we must support the following operations:

• the addition of users to the chat,
• the removal of users from the chat,
• and broadcasting messages to all users currently in the chat.

Broadcasting must be handled in a special manner. For broadcasting, we must specify our recipients: all users should receive a copy of an event dispatched. Since we have outlined the design, consider the following interface which expresses our intent,

private static class ChatState {
	private ArrayList<User> users;

	public ChatState() {}

	public void broadcast(Event evt) {}

	// Mutators
	public void addUser(User user) {}
	public void removeUser(User user) {}
}

The implementation is relatively straightforward: the users list maintains the current users in the chat and events can be broadcasted to subsequent users.

private static class ChatState {
	private ArrayList users;

	public ChatState() {
		this.users = new ArrayList();
	}

	public void broadcast(Event evt) {
		for (User recipient : users)
			recipient.dispatch(evt);
	}

	// Mutators
	public void addUser(User user) {
		users.add(user);
	}

	public void removeUser(User user) {
		users.remove(user);
	}
}

The ChatState is responsible for broadcasting events to each of the registered users. So, the ChatState must broadcast the message to individual users so that they may handle the messages individually. See the diagram for more information.

Event broadcasting

When we construct the event queue, the ChatState will act as an event forwarding mechanism for UserMessage events.

Beware that there is a dependency the above code. The broadcast method dispatches events to users by calling the User.dispatch method which doesn’t exist yet. So, let us continue onto the User behaviors.

User State Behaviors

We will outline the behavioral implementation of our User class now. Since the user is capable of receiving events, we should demultiplex the incoming events and handle them appropriately. Specifically, we want to know if a user received a message. Consider the implementation then:

private static class User {
	public String name;

	public User(String name) {
		this.name = name;
	}

	// Event demultiplexing
	public void dispatch(Event evt) {
		if (evt.getClass() == UserMessage.class) {
			UserMessage message = (UserMessage) evt;
			processMessage(message.user, message.message);
		}
	}

	// Event processing
	public void processMessage(User user, String userMessage) {
		// Ignore messages by me
		if (user.equals(this))
			return;
		System.out.println(
			name + " received message from " + 
			user.name
		);
	}
}

Take a look at the broadcast method. The type of the event argument is compared against UserMessage.class. This if-ladder is an example of event demultiplexing.

Event demultiplexing

Event demultiplexing occurs when a stream of events split its channels thereby processing the events individually rather than as a stream. This may warrant a need for an event dispatcher within a User.

When demultiplexing events, we route events to their respective handlers. Specifically, we route all of the UserMessage events to the processMessage handler and ignore the rest (arrival and departure are ignored). Once the events have been handled after demultiplexing, the behaviors of the data structure are complete.

Binding Chat State to Event Handlers

Unfortunately, now that a ChatState exists, we must pass the object, as a parameter, to the each of the event handlers so that they may change the state of the object. Consider the event handler setup for UserArrival

state.registerChannel(UserArrival.class, new ChatHandler() {
	@Override
	public void dispatch(Event evt) {
		UserArrival arrival = (UserArrival) evt;
		arrival.state.addUser(arrival.user);

		System.out.println(
			arrival.user.name + " has entered the room."
		);
	}
});

Passing state along with each event may cause significant code duplication as well as unnecessary runtime overhead. With the current design of event handlers, each of the previously designed handlers to the user events, UserArrival, UserDeparture and UserMessage must store a reference to the ChatState that they operate on.

There exists a solution which removes the code duplication and the runtime overhead. We can push the responsibility of maintaining state to the event handlers by binding the ChatState to a custom event handler. We know that this is feasible because ChatState is the same throughout the execution of this simulation.

Application-specific Chat Handlers

We will implement our own event handlers, ChatHandler, specifically for handling chat-specific events on a ChatState. Simply, this custom handler should fix the parameter common to all of our handlers, ChatState.

private static class ChatHandler extends Handler {
	protected ChatState state;
	public ChatHandler(ChatState state) {
		this.state = state;
	}
}

Afterwards, we may access the state of the chat for each subsequent ChatHandler. So, the handler registration will be slightly different with an inherited handler.

public static void registerHandlers(EventDispatcher dispatcher, ChatState state) {
	dispatcher.registerChannel(UserArrival.class, new ChatHandler(state) {
		@Override
		public void dispatch(Event evt) {
			UserArrival arrival = (UserArrival) evt;
			state.addUser(arrival.user);

			System.out.println(
				arrival.user.name + " has entered the room."
			);
		}
	});

	dispatcher.registerChannel(UserDeparture.class, new ChatHandler(state) {
		@Override
		public void dispatch(Event evt) {
			UserDeparture departure = (UserDeparture) evt;
			state.removeUser(departure.user);

			System.out.println(
				departure.user.name + " has left the room."
			);
		}
	});

	dispatcher.registerChannel(UserMessage.class, new ChatHandler(state) {
		@Override
		public void dispatch(Event evt) {
			UserMessage message = (UserMessage) evt;
			String userMessage = 
				String.format(
					"%s: %s", 
					message.user.name,
					message.message
				);
			System.out.println(userMessage);

			// Broadcast messages
			state.broadcast(message);
		}
	});
}

In our new implementation, we will use a registerHandlers helper function to initialize our event handlers with a specified event dispatcher and ChatState.

The state of the chat is updated in the above event handlers using the behavioral design that we have previously specified. Hence, we have effectively decoupled the state of the chat from the event dispatching.

Using an Event Queue

Next, we will utilize an event queue to separate concerns.

In computer science, separation of concerns (SoC) is the process of breaking a computer program into distinct features that overlap in functionality as little as possible. A concern is any piece of interest or focus in a program.

The event queue will enable us to separate the event dispatcher from the application-specific users and the chat state. That is, users should be unaware of the existence of a dispatcher especially when generating events themselves.

Additionally, when we introduce concurrency into this application (hint), the queue will also serve as a shared buffer between distributed users and the server which decouples application-independent concurrency mechanisms from our application-specific method functionality.

Conceptually, the event queue acts as a multiplexed channel which interleaves events from individual users since there is no particular order in which users may send messages. The event queue’s only concern is event multiplexing.

Event multiplexing

For now, we will simply use a simple Queue<Event> in the Java standard library to express our intent. So, to instantiate this, we use a java.util.LinkedList.

import java.util.LinkedList;

// ChatState declaration here

public static void main(String[] args) {
	EventDispatcher dispatcher = new Dispatcher();
	ChatState state = new ChatState();
	Queue<Event> eventQueue = new LinkedList<Event>();

	// Further simulation code such as event handler registration
}

Integration with Dispatcher

Since the Dispatcher is responsible for dispatching events, we should dispatch all of the events in queue when flushing the buffer.

import java.util.LinkedList;

// ChatState declaration here

public static void main(String[] args) {
	EventDispatcher dispatcher = new Dispatcher();
	ChatState state = new ChatState();
	Queue<Event> eventQueue = new LinkedList<Event>();

	// Further simulation code such as event handler registration
	// Possibly generate events beforehand

	// Dispatch all queued events
	while (!eventQueue.isEmpty()) {
		Event evt = eventQueue.remove();
		dispatcher.dispatch(evt);
	}
}

Furthermore, notice that the event queue does not interact with the ChatState. This is a highlight of separated concerns because event queues are application-independent.

Integration with Users

Before dispatching events with users, we must connect users to the event queue. Simply, we enable each individual user to reference the event queue in the implementation.

private static class User {
	public Queue<Event> eventQueue;
	public String name;

	public User(Queue<Event> eventQueue, String name) {
		this.eventQueue = eventQueue;
		this.name = name;
	}

	// Behavioral methods
}

Once users have a reference to the event queue, they are able to generate events. Specifically, we want to enable users to send messages to the chat, thereby sending a message to all other users currently in the chat.

private static class User {
	public Queue<Event> eventQueue;
	public String name;

	public User(Queue<Event> eventQueue, String name) {
		this.eventQueue = eventQueue;
		this.name = name;
	}

	// Event demultiplexing and handling methods

	// Event generation
	public void sendMessage(String message) {
		eventQueue.add(new UserMessage(this, message));
	}
}

Thus, users are now capable of sending messages without being aware of the event dispatcher and the chat state. Effectively, this is a highlight of modularity where modifications to a user’s capability in the system is independent of the modifications to the chat state and event dispatcher.

Testing the Simulation

Finally, the final source should be similar to my source code on GitHub. Now, we can test the simulation using the following main and hardcoded events:

public static void main(String[] args) {
	EventDispatcher dispatcher = new EventDispatcher();
	ChatState state = new ChatState();
	Queue<Event> eventQueue = new LinkedList<Event>();

	registerHandlers(dispatcher, state);

	// Initialize users
	User foo = new User(eventQueue, "foo");
	User bar = new User(eventQueue, "bar");
	dispatcher.dispatch(new UserArrival(foo));
	dispatcher.dispatch(new UserArrival(bar));

	// Enqueue events from individual users
	foo.sendMessage("hello, bar!");
	bar.sendMessage("hello, foo!");
	foo.sendMessage("goodbye, bar!");

	// Dispatch all queued events
	while (!eventQueue.isEmpty()) {
		Event evt = eventQueue.remove();
		dispatcher.dispatch(evt);
	}

	// Finish up simulation
	dispatcher.dispatch(new UserDeparture(foo));
	dispatcher.dispatch(new UserDeparture(bar));
}

The following output should be produced:

foo has entered the room.
bar has entered the room.
foo: hello, bar!
bar: hello, foo!
foo: goodbye, bar!
foo has left the room.
bar has left the room.

Thus, our chat simulation is complete.

Conclusion

Effective application design coupled with an event queue makes modification of the code far easier simply because we have a separation of concerns and modularity. That is, modifications to our application-specific handlers or data structures are independent of modifications to the application-independent event-driven framework, MinDispatch framework on GitHub..

It is easy to see that using the MinDispatch framework significantly simplifies the design for an event-driven application by handling the application-independent work.

Further Reading

I recommend reading Douglas Schmidt’s collection of papers on event handling and concurrency. Specifically, the Reactor Pattern has significantly influenced the design of my framework.

Another Continuation

There are two paths we can take from here:

1. Enabling concurrency and distributed computing
2. Enabling dynamic user and input and developing a chat AI

Decide. Comment your preference below.

Before reading further, beware: this post is highly dependent on knowledge of discrete mathematics (most importantly, sets). Although the concept is simple, please refer to an authoritative encyclopedia such as Wolfram Mathworld regarding unfamiliar ideas. I will highlight such esoteric ideas with emphasis.

Discussion Section Partioning Problem

Since we can rewrite this problem in terms of discrete mathematics, we will begin by decomposing the problem into sets, the fundamental structure for homogenous data.

You are given a set, \(S\), of \(n\) discussion sections where each element, \(x_i\), represents the number of students in section number \(i\). Create two partitions \(A\) and \(B\) such that the sum of their elements is minimized.

As an example, Let \(S\) be

\[\{ 3, 4, 5, 6, 8 \}\]

which can be a set of five discussion sections with three, four, five, six and eight students respectively. By staring at this list for a while, it becomes ostensible that we should split the set into

\[A = \{5, 8\}, B = \{3, 4, 6\}\]

such that their sums are equal. In regards to the problem domain, TA \(A\) receives the discussion sections with five and eight students while TA \(B\) receives the complementary sections. Consequently, the difference of the sums of their elements are minimized.

Decomposition into Optimization

To define this as an optimization problem, we would like to select a subset of S in the power set of \(S\) that minimizes difference in the sum of the subset’s elements and the sum of its complement‘s elements.

\[
\min_{X \in \mathcal{P}(S)}\left\{\left|\sum_{x \in X}^{|X|} x - \sum_{x \in S - X}^{|S-X|} x\right|\right\}
\]

Brute Force Solution

Intuitively, we can simply iterate over all subsets of \(S\) and try all possibilities in

\[
O(2^n)
\]

where \(n\) is the number of elements of the set.

This proof is trivial because there are 2ⁿ subsets for any set including the empty set (see the cardinality of the power set). Of course, this also means that the algorithm would run in exponential-time which is ridiculously slow (for arbitrarily large sets).

We can attempt to do better.

Dynamic Programming Solution

First, we will take a look at how the we can break up this problem into subproblems. Then, we will see how these subproblems are related and exploit the relationship to develop an efficient solution. Finally, I will provide an example (in case you’ve become lost in the theory).

I have written about Dynamic Programming before:
See my dynamic programming solution for the Josephus Problem if you haven’t already.

Subproblem Decomposition

We can begin by reformulating this problem into another familiar problem: the knapsack problem which seeks to find the subset of a set of items with the maximum value given a bag of finite size. To create a mapping from our problem to knapsack, we must think of this backwards.

We must let let the sum of the elements of either partition be equivalent to the bag of finite size. Next, we must determine the maximum bag capacity (or the maximum sum) in our case. Recall that difference is absolutely minimum when the sum of the elements in the partitions are equal. That is, when a partition’s sum of elements is equal to exactly half the sum of the elements of the original set:

\[
\frac{1}{2} \sum_{x \in S} x
\]

Subsequently, at each bag size, we can determine the set of elements that are closest to the desired sum.

Of course, with every dynamic programming solution, we must define boundary cases. Thus, we let \(V[i]\) be the solution for a sum of \(i\). The maximum sum, \(i\), should be within the range:

\[
\min_{x \in S}{x} \leq i \leq \frac{1}{2} \sum_{x \in S} x
\]

It is trivial then that the maximum sum for the lowerbound is equal to itself:

\[
V[\min_{x \in S}{x}] = \min_{x \in S}{x}
\]

From here, we define our recurrence relationship and realize that the maximum sum for a current solution, \(i\) is an element from the original set, \(x\) (that has not yet been selected), summed with a previous solution \(V[i-x]\):

\[
V[i] = \max_{x \in S}\{x + V[i - x] : x \not\in V[i-x] \}
\]

Thus, the best fit sum of a partition lay in \(V[max\_sum]\) where \(V[max\_sum]\) is half sum of elements of the original set.

Example Application

In the case I have lost you in theory, here is the promised example using the previously used set.

\[
\{ 3, 4, 5, 6, 8 \}
\]

\(max\_sum\) should be

\[
\frac{1}{2} \sum_{x \in S} x = \frac{1}{2} (3 + 4 + 5 + 6 + 8) = 13
\]

We apply dynamic programming between the range of three and thirteen. Starting from the bottom, we will begin applying our recurrence relationship:

\[
V[3] = \{3\} \\
V[4] = \{4\} \\
V[5] = \{5\} \\
V[6] = \{6\}
\]

There are no elements better than themselves up to six; subsequently, their solutions are equivalent to the set of themselves.

\[
V[7] = \{3\} \cup V[4] = \{3, 4\}
\]

The next subproblem has a solution which fits with with no duplicates.

\begin{aligned}
V[8] &= \{8\} \\
V[9] &= \{3\} \cup V[6] = \{3, 6\} \\
V[10] &= \{4\} \cup V[6] = \{4, 6\} \\
V[11] &= \{3\} \cup V[8] = \{3, 8\}
\end{aligned}

The above subproblems continue normally until \(V[12]\) is reached.

\[
V[12] = \{4\} \cup V[8] = \{4, 8\}
\]

Although \(\{3, V[9]\}\) comes before \(\{4, V[8]\}\) lexicographically, it does not work because \(3\) would be a duplicate in \(V[9]\)’s solution set.

\[
V[13] = \{3\} \cup V[10] = \{3, 4, 6\}
\]

Finally, we acquire one of two partitions for the solution; the other can be inferred as the complement of this. That is, the other can be calculated by

\[
B = S - V[13]
\]

Consequently, we have the partitions \(V[13]\) and \(B\) which are the solutions to our problem. That is, if we refer back to the context, TA \(A\) should be assigned discussion sections with three, four and six students and TA \(B\) should be assigned discussion sections with five and eight students. Because both TAs have thirteen students each, their partitions have the property of minimum difference.

Analysis of Dynamic Programming Solution

Recall that the number of iterations is equivalent to half of the sum,

\[
O\left(\frac{1}{2}\sum{x \in S} x\right)
\]

Each iteration is a subproblem that finds an element in the set which best fits a previous subproblem solution. The time-complexity of each subproblem is thus

\[
O(n)
\]

which can be implemented with set operations. Recall that the solution must have distinct objects and therefore each element must be checked if they already exist in the solution i.e. find() before the element can be added to the solution set, union().

Hash tables can be used for constant-time operations; however, it can also be memory-intensive. A better solution could have amortized constant-time operations with linear space.

The Union-Find data structure requires that at least one operations of find() and union() must have a logarithmic running time; the latter operation can be constant-time. However, Disjoint Set Forests enable the find() operation to be constant-time, amortized using path compression.

By multiplying the number of iterations with the cost of each iteration, we achieve the final running time:

\[
O\left(\frac{1}{2}(\sum_{x \in S} x)n\right)
\]

Thus, I have demonstrated.

Conclusions

Although a dynamic programming solution to this problem exists, it may sometimes be infeasible for arbitrarily large values of the half-sum. Consider the canonical example above. The running time of the dynamic programming solution is 65 time units whereas the power-set solution requires only 32 time units.

Making the decision of selecting either the dynamic programming solution or the power-set solution boils down to solving

\[
\min\left(\frac{1}{2}(\sum_{x \in S} x)n, 2^n\right)
\]

Overall, this is a great problem to practice algorithm design and analysis because it can be easily decomposed into discrete mathematics. There may be better solutions to this problem, and if you find one, please inform me.

Preliminary Definitions

In order to understand the projects problem, we must first describe the context in which it occurs. The people involved in this problem are of two distinct sets:

Idea People

People that propose an idea or have an explicit problem/project that they require help with

Developers

People that seek involvement in a project

A match is thus a pair: an idea person that has agreed to work with a developer. The set of matches is thus all feasible combinations of idea people and developers.

The problem of simply matching people may seem trivial. Consider a naive solution: if an idea person exists and a developer is free, then match them. Although this is intuitive (Eager Matching, see Matching Strategies), this does not guarantee satisfactory results.

We say that results are satisfactory if we can optimally maximize both the idea person and developer’s satisfaction with the matching. Thus, we produce an optimization problem:

\[
\max{\sum_{i=0}^{matches} satisfaction(i)}
\]

We must then define criteria for satisfaction. In the context of ICS projects, we say that an idea person is satisfied with the matching if their developer has the skills necessary to solve their problem; additionally, we say that a developer is satisfied with the matching if they have been sufficiently compensated for their work (whether intellectually or monetary).

The Projects Problem

The problem now can be easily defined: given a set of idea people and a set of developers, match people such that both parties are satisfied with the matching. As the Projects Coordinator for the Association of Computing Machinery (ACM) at UC Irvine, it is my duty to maximize the satisfactory matchmaking among idea people and developers. However, this problem is difficult to solve. Here is why:

First, idea people are also resource-constrained and seek to maximize developer talent while minimizing the cost. Second, developers seek to maximize their compensation while minimizing work. These two sets of people are playing a zero-sum game against one another (this can be modeled through a Minimax algorithm on a game tree). Certainly, one could argue that if we reduce this problem’s constraints, it becomes a simple maximization where both parties mutually benefit; however, in reality, there is always a cost whether it is monetary, time or other commitment.

An Example with Integers

To illustrate this problem, consider the following integer example:

Consider idea person A seeking a developer talent with minimum-bound skill requirement 5 i.e. A will not accept developers below the integer requirement. A is willing to offer a compensation of up to 2.

Then consider a pool of feasible developers (X, 2, 3), (Y, 1, 1), (Z, 6, 8). The tuple is a representation of (Candidate, Skill, Compensation). Thus, X has a skill of 2 and will only work for a compensation of 3.

It is obvious that X and Y are not feasible candidates. Additionally, A may attempt to coerce Z; however, it is unlikely that Z will work for such low compensation.

Therefore, there are no feasible matches in this scenario. Because no matches are made, productivity is stagnant (and non-existent) while both sets continue to grow.

Feasible Solutions: Matching Strategies

There are a few standard strategies that are frequently employed among small organizations. Each of these strategies may have variations; however, these are the standard approaches that I have observed as feasible solutions to this problem depending on the objective of the organization.

Eager Matching (Naive)

Matches are attempted among all feasible combinations of idea people and developers once they are available. Satisfaction was never considered (or was never guaranteed).

Benefit

Rapidly reduces the pool of idea people and developers in wait.

Cost

Low satisfaction rate.

Lazy Matching

Matches are only made once satisfaction is guaranteed by both parties. Beware that this approach may sometimes appear elitist if only absolutely satisfactory matches are made.

Benefit

High satisfaction rate.

Cost

Large pool of idea people and developers in wait.

Role-Based Matching

Developers (or other types of team members) are distributed into more subcategories (much like a Pigeonhole principle). Idea people then request for an individual of a specified subcategory. Team members are assigned accordingly by a third party (former VGDC process).

Benefit

Structured matching process.

Cost

Requires that members understand the process as well as the requirements which entail a category/title. If the structure maintains no requirements for each category, then the strategy is reduced to eager matching (with unnecessary structure).

Mentorship Strategy

Idea people have a specific problem which has an inheritance property such that new developers of arbitrary skill requirements may improve and later inherit the duties of idea people.

Benefit

Long-term investment of idea people and developers

Cost

Specific to projects that can afford long-term investments; additionally, risk is involved such that new developers are lost after long-term investment.

Discussion of ACM’s Lazy Strategy

ACM’s current strategy is lazy matching. Although incompatible matches frequently disappear (due to wait), there is significant involvement as well as progress for the few projects established through ACM.

Benefit

Consider the ACM website which, under a five-day time constraint, was well-made. Additionally, consider ICPC practice sessions, which, with only a quarter of practice, enabled a first-year student to achieve first place in a local competition against undergraduates of all levels i.e. third- and fourth-years.

Cost

Now, we consider the cost of such achievements through lazy matches. First, ACM has a significantly small board as well as a small, general member base. Second, ACM must shoulder its own financial weight, for we do not appeal with a breadth of talent as other clubs may. As a consequence, we sacrifice aggressive marketing tactics and corporate event opportunities.

General Strategy Discussion

Although I may continue to discuss the strategic positions of other organizations such as VGDC and ICSSC, they are sensitive topics of debate that I will not discuss without approval.

Instead, I will generalize that with every strategy, advantages are weighed by sacrifices (once optimal utility has been achieved). Thus, ACM sacrifices a large audience in favor of a handful of capable individuals.

We intend for ACM’s culture to be established by its few members, for each member has a duty to algorithms, theory and intellectual discussion.

Further Discussion

Certainly, there was much left out such as other criteria for satisfaction, the concept of wait, skill requirements, effective Pigeonholing, strategic implications and the simple concept of time.

If you’re interested such a topic, find me in the Irvine wild and perhaps we may have a chat.

Scope of Closures

Closures are composed with two environments: the inner and outer. The inner environment is where new, local variables are defined. The outer environment is where variables live that existed during the creation of the closure itself.

Closure Scopes

Closures have access to both environments and thus have access to variables from both the inner and outer scopes. In pseudocode, it may have the following structure.

procedure outer():
    procedure inner():
        # Do stuff
    return inner

The problems identified here are specific to the scope of closures.

This JavaScript Problem

I first encountered this problem while sifting through Douglas Crockford’s book, JavaScript the Good Parts, in the section regarding function invocation. He explains that the this keyword of functions are automatically bound to the global scope, the window object, when the function is not a method.

This is troublesome because closures cannot have access to the outer function’s this keyword without some hacking.

var obj = {};
obj.outer = function() {
	function inner() {
		console.log(this);
	}
	return inner;
}

var fn = outer();
fn();

With the above code, the console unsurprisingly logs the Window object. This strange functionality is due to the ECMAScript 5 specification on function calls.

in the HTML document object model the window property of the global object is the global object itself.

So, it isn’t necessarily incorrect that JavaScript binds the this keyword to window, for calling the function fn() is equivalent to its dependency injection variant, fn.call(window). For closures, however, we should not automatically override the scope of variables with the global scope, especially this of the outer function.

The quick and classical fix to this problem simply involves aliasing the object to a local variable of the outer environment instead.

var obj = {};
obj.outer = function() {
	var that = this;
	function inner() {
		console.log(that);
	}
	return inner;
}

var fn = outer();
fn();

The output now returns the Object as expected.

Python’s Lexical Scope Problem

Closures in Python 2.x could not change nonlocal variables. It was strange that variables in the outer scope could be accessed, but they could not be changed. This was an inherent problem in the lexical scoping rules of Python where names could only be bound to the local scope or global scope.

Since Python 3, this problem was fixed though it’s still noteworthy of discussion. See PEP 3104.

Consider the following example which increments a counter whenever the function is called.

def counter():
    count = 0;
    def inner():
        count += 1
        return count
    return inner

The above example will yield an error when executed:

>>> countr = counter()
>>> countr()
UnboundLocalError: local variable 'count' referenced before assignment

Again, the error occurs due to Python’s lexical scoping. The local variable, count is not initialized in the inner scope. We expect the variable to be initialized in the outer scope instead; however, this is not the case and the variable remains unbound.

Fortunately, Python 3 added the nonlocal keyword which enables closures to change variables in their outer environment.

def counter():
    count = 0;
    def inner():
        nonlocal count
        count += 1
        return count
    return inner

Now, the counter() works as expected:

>>> countr = counter()
>>> countr()
1
>>> countr()
2

Final Thoughts

These problems only serve to highlight the inherent difficulties with language design. Although it’s a craft tempered throughout the years, programming languages are still far from perfect. It is especially difficult with multiparadigm languages such as JavaScript and Python because of they must cater for each programming paradigm with precision.

I have no complaints for Ruby because I’m not as familiar with it as these two languages, though if anyone else has opinion on it, please free free to share.

Lexer, a Definition

To describe lexers, we must first describe a tokenizer. Tokenizers simply break up strings into a set of tokens which are, of course, more strings. Subsequently, a lexer is a type of tokenizer that adds a context to the tokens such as the type of token extracted e.g. (NUMBER 1234) whereas a simple token would be 1234. Lexers are important for parsing languages, however, that is a discussion beyond the scope of this tutorial.

For example, given the input "11 + 22 + 33", we should receive the following tokens from a lexer:

(NUMBER 11)
(BINARYOP +)
(NUMBER 22)
(BINARYOP -)
(NUMBER 33)

Note that BINARYOP refers to binary operator. Binary operators includes any operator that accepts two arguments. The archetypal example is addition which accepts two numbers, one to the left and the other to the right of the operator.

Setting-Up the Program

The input is a sentence to be scanned. For this tutorial, we will scan a simple arithmetic grammar that includes addition, multiplication and subtraction. Consequently, we will parse the following input:

public class Lexer {
	public static void main(String[] args) {
		String input = "11 + 22 - 33";
	}
}

Next, we must define the types of the tokens that we are extracting and the regular expression that they match.

Number

-?[0-9]+ Matches negative infinity to positive infinity without decimals.

Binary Operator

[*|/|+|-] Matches any standard arithmetic operators.

Whitespace

[ \t\f\r\n]+ Matches whitespace, tabs, form feeds or newlines in a sequence. Will be skipped.

public class Lexer {
	public static enum TokenType {
		// Token types cannot have underscores
		NUMBER("-?[0-9]+"), BINARYOP("[*|/|+|-]"), WHITESPACE("[ \t\f\r\n]+");

		public final String pattern;

		private TokenType(String pattern) {
			this.pattern = pattern;
		}
	}

	public static void main(String[] args) {
		String input = "11 + 22 - 33";
	}
}

Enumerations in Java can only have private constructors because there is only a finite set of objects created at run-time. Consequently, their data fields are frequently declared as final.

Finally, we declare a data structure for holding the token data. Additionally, I will override the toString() method for printing out the token’s contextual data at the end of this tutorial in the format I have mentioned earlier: (<TYPE> <DATA>).

public class Lexer {
	public static enum TokenType {
		// Token types cannot have underscores
		NUMBER("-?[0-9]+"), BINARYOP("[*|/|+|-]"), WHITESPACE("[ \t\f\r\n]+");

		public final String pattern;

		private TokenType(String pattern) {
			this.pattern = pattern;
		}
	}

	public static class Token {
		public TokenType type;
		public String data;

		public Token(TokenType type, String data) {
			this.type = type;
			this.data = data;
		}

		@Override
		public String toString() {
			return String.format("(%s %s)", type.name(), data);
		}
	}

	public static void main(String[] args) {
		String input = "11 + 22 - 33";
	}
}

Now that we have our input, token types and data structure for tokens, we may begin lexical analysis of the input string into a set of tokens with its corresponding token type.

Lexical Analysis with Regular Expressions

We begin by framing our lexical analysis method as lex(), a function which returns a list of Token objects. Additionally, we will need to import ArrayList in order to store the Token objects into the list.

import java.util.ArrayList;

public class Lexer {
	public static enum TokenType {
		// Token types cannot have underscores
		NUMBER("-?[0-9]+"), BINARYOP("[*|/|+|-]"), WHITESPACE("[ \t\f\r\n]+");

		public final String pattern;

		private TokenType(String pattern) {
			this.pattern = pattern;
		}
	}

	public static class Token {
		public TokenType type;
		public String data;

		public Token(TokenType type, String data) {
			this.type = type;
			this.name = data;
		}

		@Override
		public String toString() {
			return String.format("(%s %s)", type.name(), data);
		}
	}

	public static ArrayList<Token> lex(String input) {
		// The tokens to return
		ArrayList<Token> tokens = new ArrayList<Token>();

		// Lexer logic begins here

		return tokens;
	}

	public static void main(String[] args) {
		String input = "11 + 22 - 33";

		// Create tokens and print them
		ArrayList<Token> tokens = lex(input);
		for (Token token : tokens)
			System.out.println(token);
	}
}

Now, we need to encode all of the regular expression patterns for each of the token types into a single pattern in the algorithm shown below. This is the case where we use named capturing groups in regular expressions as (?<TYPE> PATTERN) so that once a pattern is matched, we can retrieve the token by calling its group name, the TYPE.

Additionally, we import the Pattern class to compile regular expression patterns.

import java.util.regex.Pattern;

public static ArrayList<Token> lex(String input) {
	// The tokens to return
	ArrayList<Token> tokens = new ArrayList<Token>();

	// Lexer logic begins here
	StringBuffer tokenPatternsBuffer = new StringBuffer();
	for (TokenType tokenType : TokenType.values())
		tokenPatternsBuffer.append(String.format("|(?<%s>%s)", tokenType.name(), tokenType.pattern));
	String tokenPatterns = Pattern.compile(new String(tokenPatternsBuffer.substring(1)));

	return tokens;
}

Next, we begin tokenizing by creating a Matcher object from the compiled pattern, tokenPatterns, from earlier. The matcher will return any token matched with any of the corresponding token type patterns. Note that we must also import the Matcher class here.

We will iterate through the list of token types and ask if the token type was matched. If the token returns a match, we will add it to our list of tokens with the corresponding token type and continue parsing the input.

import java.util.regex.Pattern;
import java.util.regex.Matcher;

public static ArrayList<Token> lex(String input) {
	// The tokens to return
	ArrayList<Token> tokens = new ArrayList<Token>();

	// Lexer logic begins here
	StringBuffer tokenPatternsBuffer = new StringBuffer();
	for (TokenType tokenType : TokenType.values())
		tokenPatternsBuffer.append(String.format("|(?<%s>%s)", tokenType.name(), tokenType.pattern));
	Pattern tokenPatterns = Pattern.compile(new String(tokenPatternsBuffer.substring(1)));

	// Begin matching tokens
	Matcher matcher = tokenPatterns.matcher(input);
	while (matcher.find()) {
		if (matcher.group(TokenType.NUMBER.name()) != null) {
			tokens.add(new Token(TokenType.NUMBER, matcher.group(TokenType.NUMBER.name())));
			continue;
		} else if (matcher.group(TokenType.BINARYOP.name()) != null) {
			tokens.add(new Token(TokenType.BINARYOP, matcher.group(TokenType.BINARYOP.name())));
			continue;
		} else if (matcher.group(TokenType.WHITESPACE.name()) != null)
			continue;
	}

	return tokens;
}

And the algorithm is complete! The magic of named capturing groups here happens as we match of the token types. Note that instead of matching groups by their numerical reference, matcher.group(0), we use the actual name which is far more intuitive and much easier to maintain.

Here is the complete source code:

import java.util.ArrayList;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

public class Lexer {
	public static enum TokenType {
		// Token types cannot have underscores
		NUMBER("-?[0-9]+"), BINARYOP("[*|/|+|-]"), WHITESPACE("[ \t\f\r\n]+");

		public final String pattern;

		private TokenType(String pattern) {
			this.pattern = pattern;
		}
	}

	public static class Token {
		public TokenType type;
		public String data;

		public Token(TokenType type, String data) {
			this.type = type;
			this.data = data;
		}

		@Override
		public String toString() {
			return String.format("(%s %s)", type.name(), data);
		}
	}

	public static ArrayList<Token> lex(String input) {
		// The tokens to return
		ArrayList<Token> tokens = new ArrayList<Token>();

		// Lexer logic begins here
		StringBuffer tokenPatternsBuffer = new StringBuffer();
		for (TokenType tokenType : TokenType.values())
			tokenPatternsBuffer.append(String.format("|(?<%s>%s)", tokenType.name(), tokenType.pattern));
		Pattern tokenPatterns = Pattern.compile(new String(tokenPatternsBuffer.substring(1)));

		// Begin matching tokens
		Matcher matcher = tokenPatterns.matcher(input);
		while (matcher.find()) {
			if (matcher.group(TokenType.NUMBER.name()) != null) {
				tokens.add(new Token(TokenType.NUMBER, matcher.group(TokenType.NUMBER.name())));
				continue;
			} else if (matcher.group(TokenType.BINARYOP.name()) != null) {
				tokens.add(new Token(TokenType.BINARYOP, matcher.group(TokenType.BINARYOP.name())));
				continue;
			} else if (matcher.group(TokenType.WHITESPACE.name()) != null)
				continue;
		}

		return tokens;
	}

	public static void main(String[] args) {
		String input = "11 + 22 - 33";

		// Create tokens and print them
		ArrayList<Token> tokens = lex(input);
		for (Token token : tokens)
			System.out.println(token);
	}
}

Running the Algorithm

For completeness, when we run the program, we should receive the following output.

(NUMBER 11)
(BINARYOP +)
(NUMBER 22)
(BINARYOP -)
(NUMBER 33)

Conclusion

Although lexical analysis is doable without it, named capturing groups in regular expressions certainly makes the code more intuitive and easier to maintain. It’s also nice that Java is beginning to provide features that act as syntactic sugar.

The Problem

Given three paragraphs of text in HTML, find and print all big words within the text. Big words shall be defined by anything with more than eleven characters. The initial set of paragraphs will be defined within an <article> block identified by lipsum. The solution should be printed to the <ul> identified by long_words.

Algorithm Outline

We want to outline the algorithm before we begin programming so that we’re aware of our situation, our objective and how to achieve that objective using our algorithm.

1. Extract the text from the paragraphs under the <article>.
2. Union the paragraphs into a single block of text.
3. Filter for all words longer than eleven characters.
4. Print the solution of long words into the DOM under the <ul>

Context of the Problem

I have written the problem into an HTML5 document to demonstrate the structure as per problem definition. Note here that I am using HTML5 instead of HTML4 or XHTML2.0. Additionally, we use lipsum are our boilerplate.

<!DOCTYPE html>
<html>
<head>Prelude into Underscorejs: Text Processing on the DOM</head>
<body>
<article id="lipsum">
	<h2>Three Paragraphs of Lipsum</h2>

	<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.
	Pellentesque vitae lectus at augue adipiscing facilisis in et
	dolor. Maecenas semper scelerisque blandit. Sed ut nibh eget
	purus aliquam suscipit. Nulla in facilisis leo. Etiam augue
	ligula, blandit et volutpat eget, ultrices hendrerit libero.
	Curabitur facilisis tincidunt neque, ornare viverra dui imperdiet
	ut. Suspendisse rhoncus, diam ut congue pharetra, metus tellus
	vehicula tellus, id imperdiet leo sem quis urna.<p>

	<p>Proin massa odio, malesuada quis aliquet suscipit, porta in
	arcu. Nunc ac egestas metus. Sed ac ligula vel neque molestie
	consectetur. Sed ac lacus nulla, sollicitudin interdum arcu.
	Quisque neque elit, hendrerit at mollis id, porta nec sem. In
	dapibus convallis ligula sed laoreet. Nulla non leo turpis. Sed
	dictum magna sit amet neque gravida malesuada. Donec pulvinar
	aliquam nisi, at malesuada libero posuere in. Donec ullamcorper
	accumsan eros nec interdum. Nam pharetra purus eget quam auctor
	nec placerat elit varius. Suspendisse imperdiet vehicula elit, at
	consequat dolor feugiat ut. Vestibulum ac suscipit augue.
	Curabitur scelerisque sollicitudin nisl nec sodales. Sed sed
	placerat ligula.<p>

	<p>Phasellus cursus sagittis augue, sit amet rutrum felis
	adipiscing vel. Pellentesque suscipit posuere sollicitudin. Proin
	pretium enim vel diam lobortis vel ullamcorper purus auctor.
	Vestibulum quis orci sem, nec vulputate arcu. Sed pretium
	facilisis ullamcorper. Curabitur placerat libero et quam rhoncus
	varius. Mauris bibendum felis non mi tincidunt id congue urna
	bibendum.</p>
<article>

<article>
	<h2>Long Words</h2>
	<p>In this case, we define <em>long words</em> as words with
	more than eleven characters. After pulling out these long
	words, we may provide definitions for they may be new to a
	reader's vocabulary.</p>
	<ul id="long_words"></ul>
</article>
</body>
</html>

Walking through the Underscorejs Algorithm

According to our algorithm, we must first extract the text from the paragraphs within the <article> defined by lipsum.

We can start by gaining control of the <article> tag through document.getElementById. Afterwards, we need to acquire a list of all paragraph nodes under our article. Underscorejs easily allows us to do this by filtering childNodes of the article against their nodeName; specifically, we filter against the nodeName of the <p> tag. Beware: all HTML elements have capitalized names.

function processLipsum() {
	// Get the paragraph nodes of the article
	var lipsumArticle = document.getElementById('lipsum');
	var lipsumParagraphs = _.filter(lipsumArticle.childNodes,
		function(node) {
			return node.nodeName === 'P';
		});
};

document.addEventListener("DOMContentLoaded", processLipsum, false);

Because our algorithm is dependent upon the DOM contents, we must execute our code once the entire DOM content has loaded; consequently, we bind the beginning of our function to the DOMCOntentLoaded event.

At this point, we have a list of all <p> tags that are children of the containing <article>.

Now we can simply start _.chain the list of paragraphs and process it through a set of higher-order functions sequentially to acquire our new list of big words.

Union the List of Paragraphs

First, we need to coalesce the paragraphs’ text into a single list. We can do this by first replacing all non-alphanumeric symbols and extraneous spaces with a single space through replace. Afterwards, we simply split the paragraph according to spaces such that only words are given to us in our new list.

This list processing can be done with _.map by mapping the list of paragraph to a list of words within the specified paragraphs.

Second, once the list of words have been generated, it is a deep list i.e. it contains a list of list of words originally within our paragraphs. This can easily be subverted by _.flatten which turns our list into a shallow list i.e. inner lists coalesce into the containing list.

Now, our paragraphs should have been successfully unioned into a list words as shown below.

function processLipsum() {
	// Get the paragraph nodes of the article
	var lipsumArticle = document.getElementById('lipsum');
	var lipsumParagraphs = _.filter(lipsumArticle.childNodes,
		function(node) {
			return node.nodeName === 'P';
		});

	var lipsumWords = _.chain(lipsumParagraphs)
		// Reduce all extranneous whitespace and symbols to a single space.
		// Then split the words by space.
		.map(function(node) {
			return node.innerHTML.replace(/[\W\s]+/g, ' ').split(' ');
			})
		// Union all subarrays into a large array of words.
		.flatten()
		// Return the flattened list of words
		.value();
};

document.addEventListener("DOMContentLoaded", processLipsum, false);

Filter the List of Words

This section is trivial though necessary to our objective: filter the following list to return all big words which have more than eleven characters. Simply, we will chain the _.filter function further and return the final list of words by ending our _.chain with _.value.

function processLipsum() {
	// Get the paragraph nodes of the article
	var lipsumArticle = document.getElementById('lipsum');
	var lipsumParagraphs = _.filter(lipsumArticle.childNodes,
		function(node) {
			return node.nodeName === 'P';
		});

	var lipsumWords = _.chain(lipsumParagraphs)
		// Reduce all extranneous whitespace and symbols to a single space.
		// Then split the words by space.
		.map(function(node) {
			return node.innerHTML.replace(/[\W\s]+/g, ' ').split(' ');
			})
		// Union all subarrays into a large array of words.
		.flatten()
		// Find all words with more than eleven characters.
		.filter(function(word) {
			return word.length > 11;
		})
		// Return the filtered list of words.
		.value();
};

document.addEventListener("DOMContentLoaded", processLipsum, false);

We have successfully acquired the list of big words. Now, the final task is to print the list into the DOM.

Printing to the DOM

Instead of polluting our function space, we will delegate the printing to an auxiliary function. In this function, we must create a document fragment to begin storing new <li> elements.

For each of the words we pass to the function, it will create a new list element, insert a long word into it as a text node and append it the document fragment. _.each does this for us trivially.

Finally, we append the list of list elements to the unordered list identified by long_words.

function printLongWords(words) {
	var fragment = document.createDocumentFragment();
	var listElm = null;
	_.each(words, function(word) {
		listElm = document.createElement('LI');
		listElm.appendChild(document.createTextNode(word));
		fragment.appendChild(listElm);
	});
	document.getElementById('long_words').appendChild(fragment.cloneNode(true));
};

Voila! We have successfully printed to the DOM.

Putting It All Together Now

<!DOCTYPE html>
<html>
<head>Prelude into Underscorejs: Text Processing on the DOM</head>
<script type="text/javascript" src="underscore.js"></script>
<script type="text/javascript">
function processLipsum() {
	// Get the paragraph nodes of the article
	var lipsumArticle = document.getElementById('lipsum');
	var lipsumParagraphs = _.filter(lipsumArticle.childNodes,
		function(node) {
			return node.nodeName === 'P';
		});

	var lipsumWords = _.chain(lipsumParagraphs)
		// Reduce all extranneous whitespace and symbols to a single space.
		// Then split the words by space.
		.map(function(node) {
			return node.innerHTML.replace(/[\W\s]+/g, ' ').split(' ');
			})
		// Union all subarrays into a large array of words.
		.flatten()
		// Find all words with more than eleven characters.
		.filter(function(word) {
			return word.length > 11;
		})
		// Return the list of words.
		.value();
	printLongWords(lipsumWords);
};

function printLongWords(words) {
	var fragment = document.createDocumentFragment();
	var listElm = null;
	_.each(words, function(word) {
		listElm = document.createElement('LI');
		listElm.appendChild(document.createTextNode(word));
		fragment.appendChild(listElm);
	});
	document.getElementById('long_words').appendChild(fragment.cloneNode(true));
};

document.addEventListener("DOMContentLoaded", processLipsum, false);
</script>
<body>
<article id="lipsum">
	<h2>Three Paragraphs of Lipsum</h2>

	<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.
	Pellentesque vitae lectus at augue adipiscing facilisis in et
	dolor. Maecenas semper scelerisque blandit. Sed ut nibh eget
	purus aliquam suscipit. Nulla in facilisis leo. Etiam augue
	ligula, blandit et volutpat eget, ultrices hendrerit libero.
	Curabitur facilisis tincidunt neque, ornare viverra dui imperdiet
	ut. Suspendisse rhoncus, diam ut congue pharetra, metus tellus
	vehicula tellus, id imperdiet leo sem quis urna.<p>

	<p>Proin massa odio, malesuada quis aliquet suscipit, porta in
	arcu. Nunc ac egestas metus. Sed ac ligula vel neque molestie
	consectetur. Sed ac lacus nulla, sollicitudin interdum arcu.
	Quisque neque elit, hendrerit at mollis id, porta nec sem. In
	dapibus convallis ligula sed laoreet. Nulla non leo turpis. Sed
	dictum magna sit amet neque gravida malesuada. Donec pulvinar
	aliquam nisi, at malesuada libero posuere in. Donec ullamcorper
	accumsan eros nec interdum. Nam pharetra purus eget quam auctor
	nec placerat elit varius. Suspendisse imperdiet vehicula elit, at
	consequat dolor feugiat ut. Vestibulum ac suscipit augue.
	Curabitur scelerisque sollicitudin nisl nec sodales. Sed sed
	placerat ligula.<p>

	<p>Phasellus cursus sagittis augue, sit amet rutrum felis
	adipiscing vel. Pellentesque suscipit posuere sollicitudin. Proin
	pretium enim vel diam lobortis vel ullamcorper purus auctor.
	Vestibulum quis orci sem, nec vulputate arcu. Sed pretium
	facilisis ullamcorper. Curabitur placerat libero et quam rhoncus
	varius. Mauris bibendum felis non mi tincidunt id congue urna
	bibendum.</p>
<article>

<article>
	<h2>Long Words</h2>
	<p>In this case, we define <em>long words</em> as words with
	more than eleven characters. After pulling out these long
	words, we may provide definitions for they may be new to a
	reader's vocabulary.</p>
	<ul id="long_words"></ul>
</article>
</body>
</html>

Conclusion

Higher-order functions significantly simplify the processing of stream-based or list-based data such as text.

Using JavaScript’s interface into the DOM, we were able to show how functional programming (though impure) may have a place on the web to simplify common computational tasks and even DOM tasks.

Additionally, while playing with higher-order functions on Haskell, I wanted to see how they may simplify a standard set of computational tasks that I would normall write in C. Fortunately, JavaScript allows me to do this in a multi-paradigm fashion.

Wait! What Are These Magical, Higher-Order Functions?

Well, I’ll turn to the pure, functional language, Haskell, to describe it correctly:

A higher-order function is a function that takes other functions as arguments or returns a function as result.

Standard Computational Task

The situation: a professor has just finished grading the final exams out of a hundred for his eight-student classroom. He would like to know the top scores (above 80), the highest score (maximum) and the average of the scores.

Class Scores: [98, 76, 45, 84, 32, 55, 88, 76]

From the problem description, we have the following set of tasks with constraints:

1. Retrieve all scores above eighty.
2. Retrieve the maximum score from the list.
3. Retrieve the running sum of the scores and divide it by the number of scores (mean).

Now that we have described the problem, let's attempt a standard solution with C.

C-Style Solution

The following solution does not have the immutable array data structure; however, I ensured that there were no side-effects which may mutate the original array after calculations. Instead, all solutions are written to a new result variable as indicated by Calculation results section.

Furthermore, I fissioned the calculation loops to represent how Underscorejs implements their higher-order functions. Note that it would have been optimal if these operations were fused instead.

Loop fission (or loop distribution) is a possible compiler optimization which utilizes the locality of reference.

#include <stdio.h>
#define NUM_SCORES 8

int main(int argc, char* argv[]) {
	// Calculation results
	int top_scores[NUM_SCORES];
	int highest_score = 0;
	int mean = 0;

	// Input data
	int scores[NUM_SCORES];
	scores[0] = 98;
	scores[1] = 76;
	scores[2] = 45;
	scores[3] = 84;
	scores[4] = 32;
	scores[5] = 55;
	scores[6] = 88;
	scores[7] = 76;

	// Iterators
	int i;
	int top_scores_counter = 0;
	int running_sum = 0; // Memo

	// Calculate the top scores above 80
	for (i = 0; i < NUM_SCORES; ++i)
		if (scores[i] > 80)
			top_scores[top_scores_counter++] = scores[i];

	// Calculate the highest score
	for (i = 0; i < NUM_SCORES; ++i)
		if (scores[i] > highest_score)
			highest_score = scores[i];

	// Calculate the running sum
	for (i = 0; i < NUM_SCORES; ++i)
		running_sum += scores[i];
	// Calculate the mean after the finding the running sum
	mean = running_sum / NUM_SCORES;

	// Print the data
	printf("Top Scores: ");
	for (i = 0; i < top_scores_counter; ++i)
		printf("%d ", top_scores[i]);
	printf("\n");

	printf("Highest Score: %d \n", highest_score);
	printf("Average Score: %d \n", mean);

	return 0;
}

When executed, the above code should print the following results to the standard output:

Top Scores: 98 84 88 
Highest Score: 98 
Average Score: 69

Disregarding the scaffolding here, the the C-style solution is verbose simply because of the majority of operations in the for-loops. Sure, we can coalesce the loops through the loop fusion optimization but why aren't these operations provided by the standard library by default?

This problem can naturally be solved through higher-order functions which apply functions to each iteration through a loop.

C++ STL provides a notion of higher-order functions through their concept of function objects.

Underscorejs Solution

The C-style solution is applicable to almost all programming languages that offer the standard set of control structures with for-loop and if-else though I do not apply it as frequently as is applicable. It's verbose. Without higher-order functions, I would implement it in JavaScript as I have above.

Fortunately, Underscorejs provides a standard set of higher-functions for reducing the verbosity of our code. We could simply use _.filter to retrieve the top scores, _.max to find the highest scores and _.reduce to find the running sum for the mean.

// Initial data
var scores = [98, 76, 45, 84, 32, 55, 88, 76];

// Calculates the top scores
var top_scores = _.filter(scores, function(score) {
	return score > 80;
});

// Calculate the highest score
var highest_score = _.max(scores);

// Calculate the running sum
var running_sum = _.reduce(scores, function(memo, score) {
	return memo + score;
}, 0);
var mean = running_sum / scores.length;

// Print the data
console.log("Top Scores: " + top_scores);
console.log("Highest Score: " + highest_score;
console.log("Average Score: " + mean);

It's easy to see how our code verbosity has been significantly reduced through the use of the higher-order functions provided by Underscorejs. There are native implementations of the functions used above, namely, Array.prototype.filter and Array.prototype.reduce; nonetheless, I use Underscorejs for cross-browser compatibility.

How Underscorejs implements Higher-Order Functions

It may be obvious that these higher-order functions parallel to the C-style code above by applying a function to each iteration of a loop; still, I will make explicit its implementation. Moreover, I will add my personal annotations to the source code to help guide you through it.

Consider the implementation of _.filter which returns a new array of filtered values given a list (obj) and a boolean function (iterator).

Recall that a higher-order function either takes a function as an argument or returns a function; subsequently, _.filter is a higher-order function by definition of taking a function as an argument.

_.filter = _.select = function(obj, iterator, context) {
	// The new results array to attempt immutability
	var results = [];
	
	// Edge case if the list is empty; simply return nothing
	if (obj == null) return results;

	// Use the native implementation if it's available.
	if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);

	// Real work is delegated?
	each(obj, function(value, index, list) {
		// Returns the value if the boolean function evaluates to true
		if (iterator.call(context, value, index, list)) results[results.length] = value;
	});
	return results;
};

First, let's consider all of the function cases:

Empty List

Returns a new, empty list. Trivial.

Native Implementation Available

It's worth noting here that _.filter utilizes the native JavaScript implementation as denoted by the nativeFilter case. If the native implementation is unavailable, we move on to support backwards-compatibility and cross-browser compatibility through this library.

Default Case

Delegates the action to another function, _.each. Well, we haven't seen a loop yet but we're about to. Let's consider the delegated action then.

var each = _.each = _.forEach = function(obj, iterator, context) {
	// Base case if the list is empty
	if (obj == null) return;

	// Use the native implementation if it's available
	if (nativeForEach && obj.forEach === nativeForEach) {
		obj.forEach(iterator, context);

	// JS Hacking here to test whether obj can be accesed by a numerical index
	} else if (obj.length === +obj.length) {
		for (var i = 0, l = obj.length; i < l; i++) {
			if (i in obj && iterator.call(context, obj[i], i, obj) === breaker) return;
		}

	// Default case for objects with generic keys
	} else {
		for (var key in obj) {
			if (_.has(obj, key)) {
				if (iterator.call(context, obj[key], key, obj) === breaker) return;
			}
		}
	}
};

There's quite a few more base cases here so I'll truncate by skipping the base case and native implementation as I've already explained before.

Since the last two cases are similar, I'll aggregate them into the same case:

Index Accessible & Default Case

This is where the real-action is. Simply, this case applies an arbitrary function to the list at every index.

This arbitrary function application allows us significantly reduce the amount of code we must write. The only caveat here is that the _.each function can mutate the original data structure which defies the immutability concept of functional programming.

Simplifying the Data Flow through the Framework

To best see the flow of operations through the framework, I've simplified the framework to remove unnecessary code for the purpose of this article.

var each = _.each = _.forEach = function(obj, iterator, context) {
	for (var i = 0, l = obj.length; i < l; i++) {
		if (i in obj && iterator.call(context, obj[i], i, obj) === breaker) return;
};

_.filter = _.select = function(obj, iterator, context) {
	// The new results array to attempt immutability
	var results = [];
	
	// Real work is delegated?
	each(obj, function(value, index, list) {
		// Returns the value if the boolean function evaluates to true
		if (iterator.call(context, value, index, list)) results[results.length] = value;
	});
	return results;
};

Writing your own set of higher-order functions should be just as simple.

Conclusion

As a prelude, there will be more to come on Underscorejs.

I've shown the prowess of higher-order functions which may apply to any language that implements them and it's always worth considering to frame these common operations under a common library to reduce verbosity in future code. Now that higher-order functions have been explained, I will demonstrate practical applications of the library.

The Chat Application Simulation Revisited

Our objective once again is to simulate the events of a chat application by explicitly specifying a set of events.

However, we will no longer define the flow of data through our system for we have a framework which handles this. Instead, we can simply define the set of events and processes that our system must simulate.

Events of a Chat Application

User Arrival

Occurs when a user arrives to a room.

User Departure

Occurs when a user departs from a room.

User Message

Occurs when a user sends a message to a room.

We want to process such events by simply printing out the standard output.

foo has entered the room.
bar has entered the room.
foo: hello, bar!
bar: hello, foo!
foo: goodbye, bar!
foo has left the room.

Through the observations above, we should be able to quickly design our program in two steps: model the events and process the events. Finally, we can dispatch events to test our design.

Prerequisites

First, you must download the MinDispatch source and package it with your current project which we will name ChatEventMachine.

Coding the Simulation with MinDispatch

We modeled our events and now we must consider how they will be routed by the event dispatcher of our framework.

Event Dispatcher

Since our dispatcher on our framework is responsible for routing events to their handlers, we start by identifying the events necessary as we have above. Afterwards, we simply need to register the events to a respective set of event handlers which process each event accordingly.

First: Model the Events

Let’s begin with modeling the events specified:

public class ChatEventMachine {
	private static class User {
		public String name;

		public User(String name) {
			this.name = name;
		}
	}

	private static class UserArrival extends Event {
		public User user;

		public UserArrival(User user) {
			this.user = user;
		}
	}

	private static class UserDeparture extends Event {
		public User user;

		public UserDeparture(User user) {
			this.user = user;
		}
	}

	private static class UserMessage extends Event {
		public User user;
		public String message;

		public UserMessage(User user, String message) {
			this.user = user;
			this.message = message;
		}
	}
}

In our code above, we use an auxilliary User class which helps us encapsulate data which is only associated to the user such as the user’s name.

User classes frequently associate with many more properties such as a unique user id, password, email and more depending on the application.

Each of our events provide sufficient data for their handlers to use. The constructors of the new events, though unnecessary, makes dispatching easier as will be seen later in this tutorial.

Second: Route Events to Handlers

After our events have been successfully modelled, we can easily route events to handlers through the event dispatcher within our framework.

public class ChatEventMachine {
	// Event models

	public static void main(String[] args) {
		EventDispatcher dispatcher = new EventDispatcher();

		dispatcher.registerChannel(UserArrival.class, new Handler() {
			@Override
			public void dispatch(Event evt) {
				UserArrival arrival = (UserArrival)evt;

				System.out.println(arrival.user.name + " has entered the room.");
			}
		});

		dispatcher.registerChannel(UserDeparture.class, new Handler() {
			@Override
			public void dispatch(Event evt) {
				UserDeparture departure = (UserDeparture)evt;

				System.out.println(departure.user.name + " has left the room.");
			}
		});

		dispatcher.registerChannel(UserMessage.class, new Handler() {
			@Override
			public void dispatch(Event evt) {
				UserMessage message = (UserMessage)evt;
				String userMessage = String.format("%s: %s", message.user.name, message.message);
				System.out.println(userMessage);
			}
		});
	}
}

In the code above, we simply register a set of channels by mapping an event subclass to a new handler through a HashMap according to our framework implementation. Note here that I simply create a new, unique event handler for each event since each event requires a unique process.

Third: Dispatch Events to Simulate

Since our event dispatcher has now been set up at this point, we can start dispatching a set of events to simulate a chat application. This marks the beginning of control starting from the event dispatcher.

Dispatcher with Control

In this simple example, I will hard-code dispatched events by manually writing the constructors for the necessary objects and dispatching them through the framework’s dispatcher.

public class ChatEventMachine {
	// Event models

	public static void main(String[] args) {
		// Dispatcher and handler definitions

		User foo = new User("foo");
		User bar = new User("bar");
		dispatcher.dispatch(new UserArrival(foo));
		dispatcher.dispatch(new UserArrival(bar));
		dispatcher.dispatch(new UserMessage(foo, "hello, bar!"));
		dispatcher.dispatch(new UserMessage(bar, "hello, foo!"));
		dispatcher.dispatch(new UserMessage(foo, "goodbye, bar!"));
		dispatcher.dispatch(new UserDeparture(foo));
	}
}

At this point, our chat application simulator is complete. When we execute the main method of this program, we achieve the following:

foo has entered the room.
bar has entered the room.
foo: hello, bar!
bar: hello, foo!
foo: goodbye, bar!
foo has left the room.

The full source at the end of our tutorial:

public class ChatEventMachine {
	private static class User {
		public String name;

		public User(String name) {
			this.name = name;
		}
	}

	private static class UserArrival extends Event {
		public User user;

		public UserArrival(User user) {
			this.user = user;
		}
	}

	private static class UserDeparture extends Event {
		public User user;

		public UserDeparture(User user) {
			this.user = user;
		}
	}

	private static class UserMessage extends Event {
		public User user;
		public String message;

		public UserMessage(User user, String message) {
			this.user = user;
			this.message = message;
		}
	}

	public static void main(String[] args) {
		EventDispatcher dispatcher = new EventDispatcher();

		dispatcher.registerChannel(UserArrival.class, new Handler() {
			@Override
			public void dispatch(Event evt) {
				UserArrival arrival = (UserArrival)evt;

				System.out.println(arrival.user.name + " has entered the room.");
			}
		});

		dispatcher.registerChannel(UserDeparture.class, new Handler() {
			@Override
			public void dispatch(Event evt) {
				UserDeparture departure = (UserDeparture)evt;

				System.out.println(departure.user.name + " has left the room.");
			}
		});

		dispatcher.registerChannel(UserMessage.class, new Handler() {
			@Override
			public void dispatch(Event evt) {
				UserMessage message = (UserMessage)evt;
				String userMessage = String.format("%s: %s", message.user.name, message.message);
				System.out.println(userMessage);
			}
		});

		User foo = new User("foo");
		User bar = new User("bar");
		dispatcher.dispatch(new UserArrival(foo));
		dispatcher.dispatch(new UserArrival(bar));
		dispatcher.dispatch(new UserMessage(foo, "hello, bar!"));
		dispatcher.dispatch(new UserMessage(bar, "hello, foo!"));
		dispatcher.dispatch(new UserMessage(foo, "goodbye, bar!"));
		dispatcher.dispatch(new UserDeparture(foo));
	}
}

Conclusion

I was able to write this code within ten minutes; consequently, we see the power of a simple, event-driven framework, namely, MinDispatch, in quickly modelling event-based system and handling it accordingly.

A few people may notice that this approach is capable of modeling various live systems such as multiplayer gaming where a set of players may emit events to interact with the world e.g. opening chests, communicating with others and fight sequences.

I purposely ommitted a parse file or dynamic input stream; however, I plan to continue this tutorial by extending our application to include a dynamic stream of events as shown below:

Dispatcher With Event Queue

With the above diagram as a treat for the next post in this series, please look forward to reading about building a simple AI to respond to chat events!