1. Zachary Anderson
  2. polic


Author: Zachary Anderson (zanderso@acm.org)

Poli-C provides an interface through which applications running on a single
machine can obtain resource guarantees even though there may be many other
applications running at the same time.


I.   Intro, Design Overview, Further Reading
II.  Obtaining
III. Dependencies
IV.  Build & Install
V.   Use
VI.  Contributing, License
VII. Contact

I. Intro, Design Overview, Further Reading

To achieve better performance, applications are being written using low-level
OS interfaces to "pin" various bits of state to various bits of hardware:
threads to cores, memory to specific NUMA nodes, and so forth. While this
pinning may improve the performance of one application when the application's
assumption that it is running alone on a system is true, when there are other
application's as well, which may also be doing the same sort of pinning,
performance can be grievously harmed. That is, if an application's assumption
that it has exclusive access to the resources it pins is violated, then
performance will decrease rather than increase.

The goal of Poli-C is to allow applications to obtain guarantees of exclusive
access to resources. Then, several applications that "pin" resources may all run
at the same time without interference. In particular, Poli-C targets single
applications that use a variety of parallel libraries simultaneously, which we
call hierarchically-parallel applications. Poli-C prevents different parallel
components from competing for resources.

This is achieved as follows. A system-level daemon running with privileges
(policd) divides system resources up into to two parts. One part is for shared
use by applications that don't make explicit requests for resources. The other
part is for applications that do make explicit requests for resources to policd.
When any new process is created in the system, policd sees it, and restricts it
to using only those resources in the first part. Then, if the process makes
explicit resource requests, it can gain exclusive access to resources in the
second part.

Applications submit resource requests to policd by sending it constraints
that describe a subset of system resources that are acceptable to it. If the
resources are available, they are granted to the application and it continues
running. If they are not available, the application is blocked and placed on a
queue in policd. When new resources come available, policd decides how to
distribute them by collecting together all of the constraints from all the
applications, weighting applications at the front of the queue more heavily, and
then solving the collected constraints to find how the new resources should be

The code in this repository implements the above mentioned techniques. Policd
is implemented in C++ and is fairly-well documented. A C API through which
applications can interact with policd is provided (libpolic). Ports of some
parts of this library to C++ and Python can be found in the ports/
subdirectory. Also in that subdirectory is a C compiler front-end (policc) that
accepts language extensions that make the API easier to use from C.

The repository also includes a collection of utility libraries. librk is a
collection of the "Resource Kinds" that policd can manage. librkreg is a
registry of Resource Kinds used by both policd and libpolic. And libsmt is the
interface to an SMT solver used by polic to solve constraints.

A paper describing an earlier implementation of Poli-C (without the scheduling
features in policd, and other differences) can be found by searching for:

Zachary Anderson. Efficiently Combining Parallel Software using Fine-grained,
  Language-level, Hierarchical Resource Management Policies. OOPSLA 2012.

II. Obtaining

hg clone https://bitbucket.org/zanderso/polic

III. Dependencies

Required software:

A reasonably recent version of Linux
CMake     - Ubuntu packages: cmake cmake-data
Ocaml     - Ubuntu packages: ocaml ocaml-base ocaml-base-nox
Google protocol buffers - Ubuntu packages: libprotobuf-c0 libprotobuf-c0-dev
  libprotobuf-dev libprotobuf-lite7 libprotobuf7 libprotoc-dev
  protobuf-c-compiler protobuf-compiler
Boost     - Ubuntu packages: libboost-dev libboost-python-dev
Z3        - Download from Microsoft
Doxygen   - Ubuntu package: doxygen

Also probably other things I'm overlooking. Let me know.

IV. Build & Install

$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

Check that everything went okay:

$ touch smt.debug.txt
$ sudo policd -f smt.debug.txt
policd: [policd] Daemon starting up.
[policd] Child process created: 22323
$ make test
$ sudo policd -k [for clean shutdown of policd]

V. Use

See ports/c++/test and ports/python/test for examples.

VI. Contributing, License

This software is licensed under the 3-clause BSD license in the LICENSE file
distributed with the source code.

VII. Contact

Zachary Anderson