Why do quotas exist in software? Their role is to curtail overages consumed by a program. We could let the hardware decide how to handle these situations, but users probably wouldn't appreciate that much. How are quotas measured and how do we decide on an upper limit that regulates the consumption of one resource or another? The easy way to decide on a upper quota limit is to measure the physical hardware limits. Portions of the physical resource are made available to software that needs it. Allocating quota limits gets interesting when several competing software units are in contention for it. Abstract software objects that need memory, a thread that needs CPU time, or an entire program that needs both - these are all things that need resources and also need quotas.
Think about programs running on your operating system. The OS to decides who gets to use the CPU at any given time. If there is more than one CPU, the same logic applies - it is also up to the OS to decide which programs get to use each CPU. This is an example of a software quota. Once the program starts executing instructions, it only has so long before it must relinquish control of the CPU. This quota, the number of instructions executed by the program during it's CPU occupancy, is established by the OS. The best a program can do is manage it's own internal quotas.
What types of resources would a program want to restrain? If the underlying operating system manages physical hardware access, why bother? In dynamic programming languages, we don't need to explicitly allocate memory or tell the threading mechanism to switch contexts. There is more to quota management in software than just the physical hardware limitations.
Software is created with a problem domain in mind. In object-oriented software, different classes represent different concepts in the problem domain. Can we use these concepts as a basis to assign quota limits? For instance, if I've got two containers, one that stores user objects and one that stores document objects, I can limit these as I deem fit. I could give the user object container a quota that limits it to having no more than 100 objects at a given time. I could limit that document container to having only 10. I just made these limits up. The point is that you have the ability to do this based on the business requirements of your software, not necessary having to occupy all physical resources until the OS says your quota is exhausted.
The same idea applies to processor time within your program. If your application has several threads, you are in control of what domain concept gets to use the CPU, not leaving it up to the the OS that knows nothing about your problem domain. Understanding the domain concepts in your code and the ability to assign quotas to them gives you much more control and flexibility than you may have thought possible.
Sunday, November 28, 2010
Tuesday, November 23, 2010
jQuery UI Overall Progress Bar
The jQuery UI Javascript user interface library has a progress bar widget used to indicate the progress of something. That something can be anything, something happening locally in the browser or some server process. Sometimes it is useful to show the overall progress of several smaller, but related tasks. It would be nice if we could automate this with a specialized progress bar widget.
Thankfully, we can specialize the progress bar widget for this purpose. We can create a progress bar that observes a set of other progress bars to measure and display the overall progress. Here is an example of how we might go about doing this.
Here is the HTML markup:
Here we create four progress bar widgets. The first three are server processes that we want to show the progress of. The fourth progress bar uses a custom progress bar widget that we'll show below.
Here is the demo Javascript, demo.js, that will simulate the server processes:
Here, we set a timer that will update the three server precesses. The progress bar widgets are in turn updated.
Finally, we have overallprogress.js, our custom progress bar widget:
The overallprogress widget takes a subject parameter when it is created. The subject is observed by the overall progress widget. In our example, it is passed a jQuery object containing the three regular progress bar widgets. It then listens for progressbarchange events, on which, it updates the overall progress.
The reason we defined a new widget for this purpose is that it is generic enough to be useful in other contexts. With custom widgets, we can encapsulate a lot of the common stuff that can be reused. Here is what overallprogress looks like in action:
Thankfully, we can specialize the progress bar widget for this purpose. We can create a progress bar that observes a set of other progress bars to measure and display the overall progress. Here is an example of how we might go about doing this.
Here is the HTML markup:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Custom Progress Bar</title>
<link href="jqueryui/css/redmond/jquery-ui-1.8.5.custom.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="jqueryui/js/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="jqueryui/js/jquery-ui-1.8.5.custom.min.js"></script>
<script type="text/javascript" src="js/overallprogress.js"></script>
<script type="text/javascript" src="js/demo.js"></script>
<script type="text/javascript">
$(document).ready(function(){
$("#sp1, #sp2, #sp3").progressbar();
$("#ov").overallprogress( {subject: $("#sp1, #sp2, #sp3")} );
timer();
});
</script>
<style type="text/css">
.progress {
width: 25%;
}
.container {
padding: 10px;
}
</style>
</head>
<body>
<h1 class="ui-widget ui-widget-header">Custom Progress Bar</h1>
<div class="container ui-widget ui-widget-content">
<p>Server Process 1</p>
<div id="sp1" class="progress"></div>
<p>Server Process 2</p>
<div id="sp2" class="progress"></div>
<p>Server Process 3</p>
<div id="sp3" class="progress"></div>
<p>Overall Progress</p>
<div id="ov" class="progress"></div>
</div>
</body>
</html>
Here we create four progress bar widgets. The first three are server processes that we want to show the progress of. The fourth progress bar uses a custom progress bar widget that we'll show below.
Here is the demo Javascript, demo.js, that will simulate the server processes:
function timer(){
var v1 = $("#sp1").progressbar("value");
var v2 = $("#sp2").progressbar("value");
var v3 = $("#sp3").progressbar("value");
v1 += 5;
v2 += 10;
v3 += 5;
if (v1 > 100) {
v1 = 100;
}
if (v2 > 100) {
v2 = 100;
}
if (v3 > 100) {
v3 = 100;
}
if ( (v1 + v2 + v3) < 300){
setTimeout("timer()", 1000);
}
$("#sp1").progressbar("value", v1);
$("#sp2").progressbar("value", v2);
$("#sp3").progressbar("value", v3);
}
Here, we set a timer that will update the three server precesses. The progress bar widgets are in turn updated.
Finally, we have overallprogress.js, our custom progress bar widget:
$.widget("ui.overallprogress", $.ui.progressbar, {
options: {
subject: false
},
_init: function () {
$.ui.progressbar.prototype._init.call(this);
var subject = this.options.subject;
var overall = this;
if (subject) {
subject.bind("progressbarchange", function(event, ui) {
var total = 0;
$.each(subject, function(){
total += $(this).progressbar("value");
});
overall.value(total/subject.size());
});
}
},
});
The overallprogress widget takes a subject parameter when it is created. The subject is observed by the overall progress widget. In our example, it is passed a jQuery object containing the three regular progress bar widgets. It then listens for progressbarchange events, on which, it updates the overall progress.
The reason we defined a new widget for this purpose is that it is generic enough to be useful in other contexts. With custom widgets, we can encapsulate a lot of the common stuff that can be reused. Here is what overallprogress looks like in action:
Friday, November 12, 2010
API Documentation
Creating API documentation is a tedious task at best. Automating this process removes most drudgery involved. Programmers glimpse at API documentation at several points throughout the day. We do this to confirm doubts or to make sure that the function was in fact returning an integer type. Not only does automated documentation generation safe us effort, it is also a time saver. Is there a need for human intervention, given that we have tools at our disposal to write API documentation for us? Are the tools really that good? And if not, if they're still lacking in one respect or another, will they ever replace us entirely?
What exactly do automatic code generators do? Put simply, they collect oodles of software system information and render it in a programmer-friendly format. The basic idea is to parse the source code tree of the project and write the documentation output. The format of the documentation can be anything really, but common forms are PDF and HTML. HTML is probably the best in most situations as it is easier to navigate and usually looks better.
Automatically generated API documentation depends largely on code higher-level code structures, not necessarily the low-level file operations and so-on. Modules, classes, and functions are the preeminent descriptions that make API documentation useful. Finer details about these high-level units can also be included by the documentation generator. Function parameters, return types, and class attributes - all relevant things programmers want to read about.
We annotate these these high-level language constructs using comments which are also captured by some of these documentation-generating tools. If you use Python, you have the added privilege doc-strings, which are part of the code objects themselves. In either case, you, the developer, have the ability to extend the content of the generated API documentation. You're effectively writing documentation and code at the same time. Sounds great, doesn't it? The difficulty with this approach is intent. Are code documentation and API documentation the same thing?
Documenting code is all about explaining the "nitty-gritty" to those with the misfortune of reading your code. You've agonized over strenuous details and need to walk any reading eyes through it. Probably this isn't the kind of thing we care to see in API documentation. If I need to look up something specific in the API documentation, I don't want to be bothered by big chunks of "this attribute needs to be reset after the....". Encapsulation also applies to documentation.
How do programmers format the comments lifted from the code by generators? Documentation tools do a fine job of formatting language constructs like classes, functions, variables, etc. What they can't do is format text embedded inside an explanation. In the documentation of a function, I'll sometimes want to see a brief paragraph that tells me why the state of the file object stored in an output stream queue changes. It is helpful to format text inside these explanations as well as link to other documents. A popular format for writing API documentation seems to be reStructuredText. What this amounts to is programmers using a markup language within the programming language. This adds an unnecessary burden - especially since comments should be geared more toward the low-level.
There really is no substitute for automatically generating the code structure used in API documentation. The only alternative is to do it manually, which is excessively tedious. But at the same time manually writing the API documentation gives you freedoms you don't necessarily have when generating it via code comments. For one thing, you're not legally bound for life to a single tool. You can format as you deem necessary. You're also not restricted by the configuration constraints generation tools impose - you can document as much or as little code as you want. Whichever method you choose, just be sure that good documentation is the result.
What exactly do automatic code generators do? Put simply, they collect oodles of software system information and render it in a programmer-friendly format. The basic idea is to parse the source code tree of the project and write the documentation output. The format of the documentation can be anything really, but common forms are PDF and HTML. HTML is probably the best in most situations as it is easier to navigate and usually looks better.
Automatically generated API documentation depends largely on code higher-level code structures, not necessarily the low-level file operations and so-on. Modules, classes, and functions are the preeminent descriptions that make API documentation useful. Finer details about these high-level units can also be included by the documentation generator. Function parameters, return types, and class attributes - all relevant things programmers want to read about.
We annotate these these high-level language constructs using comments which are also captured by some of these documentation-generating tools. If you use Python, you have the added privilege doc-strings, which are part of the code objects themselves. In either case, you, the developer, have the ability to extend the content of the generated API documentation. You're effectively writing documentation and code at the same time. Sounds great, doesn't it? The difficulty with this approach is intent. Are code documentation and API documentation the same thing?
Documenting code is all about explaining the "nitty-gritty" to those with the misfortune of reading your code. You've agonized over strenuous details and need to walk any reading eyes through it. Probably this isn't the kind of thing we care to see in API documentation. If I need to look up something specific in the API documentation, I don't want to be bothered by big chunks of "this attribute needs to be reset after the....". Encapsulation also applies to documentation.
How do programmers format the comments lifted from the code by generators? Documentation tools do a fine job of formatting language constructs like classes, functions, variables, etc. What they can't do is format text embedded inside an explanation. In the documentation of a function, I'll sometimes want to see a brief paragraph that tells me why the state of the file object stored in an output stream queue changes. It is helpful to format text inside these explanations as well as link to other documents. A popular format for writing API documentation seems to be reStructuredText. What this amounts to is programmers using a markup language within the programming language. This adds an unnecessary burden - especially since comments should be geared more toward the low-level.
There really is no substitute for automatically generating the code structure used in API documentation. The only alternative is to do it manually, which is excessively tedious. But at the same time manually writing the API documentation gives you freedoms you don't necessarily have when generating it via code comments. For one thing, you're not legally bound for life to a single tool. You can format as you deem necessary. You're also not restricted by the configuration constraints generation tools impose - you can document as much or as little code as you want. Whichever method you choose, just be sure that good documentation is the result.
Monday, November 1, 2010
HTML Forms
Forms are useful tools for collecting information, whether they're physical, or or your computer screen. When we need specific bits of information, brevity is of virtue. Collecting these data fragments are why forms exist. A form value is as simple as a yes or no. They're as complex as a line or two of text. The web-equivalent of a paper form is the HTML form element. Given that a form is used to capture information, and, that is what it is good at, why aren't forms used more often in web pages? Not using a form element to gather user input is a classic example of reinventing the wheel. So why do we do it?
Maybe we don't like to use forms because we associate them with legacy-style HTML pages from the nineties. But forms aren't visual elements. Its the elements within the form that are displayed, the text inputs, the radio buttons, and selectors you can see. If a form is a non-visual element, that is, a structural element used to group others, why go out of our way to submit data by other means?
The ultimate purpose of a form element is pragmatic - it is functional, not presentational. There are two other data items forms store in addition to user input - the action and the method. The form action is a URI. A URI usually represents some data resource on the server. The form method corresponds to the HTTP method used to submit the form. When a form is submitted, the HTTP request is made with the stored action and method.
Another example of an element that stores an action and a method is an anchor tag. Links store the action in the href attribute. Just like forms, actions are URIs that represent resources on the server. So where exactly is the method stored? Links store the HTTP GET method implicitly. There is no way to click a link that sends a POST request without intervening with Javascript. Unlike forms, however, links take on the dual role of being both a functional and a presentational element - you can see links on the web page.
Since links can't send anything other than GET requests, we are more likely to use Javascript - assuming we want to make a POST request by clicking a link. This gives us full control over the HTTP request. When a user clicks a link, or any other element listening for click events, some Javascript function is triggered that will assemble the HTTP request. The request is then sent asynchronously behind the scenes. This work flow is especially easy with libraries such as jQuery. All it takes is a few lines of code to build the request and send it.
There is nothing inherently wrong with this approach - only writing code to do exactly what a form does is discouraged. This is especially true with GET requests that are sent as a result of user input. For example, we have a page that lists objects in a table. We also have a select element that filters the list by some field. When that selector changes, the page is refreshed with the new GET parameters. The request is triggered by binding the selector change event to a Javascript function. The function then builds the URI and sends the request. Alternatively, the select element is part of a form that stores the URI, and the method. Our function would simply submit the form.
Using forms as they were intended is good web-programming practice. They are perfect for collecting small pieces of information and map well to abstractions that exist on a server. Forms store HTTP methods, action URIs, group input elements, and assemble HTTP requests so that you don't have to. They exist for a practical purpose. Use them to your advantage and you'll be surprised at how much code you don't have to write.
Maybe we don't like to use forms because we associate them with legacy-style HTML pages from the nineties. But forms aren't visual elements. Its the elements within the form that are displayed, the text inputs, the radio buttons, and selectors you can see. If a form is a non-visual element, that is, a structural element used to group others, why go out of our way to submit data by other means?
The ultimate purpose of a form element is pragmatic - it is functional, not presentational. There are two other data items forms store in addition to user input - the action and the method. The form action is a URI. A URI usually represents some data resource on the server. The form method corresponds to the HTTP method used to submit the form. When a form is submitted, the HTTP request is made with the stored action and method.
Another example of an element that stores an action and a method is an anchor tag. Links store the action in the href attribute. Just like forms, actions are URIs that represent resources on the server. So where exactly is the method stored? Links store the HTTP GET method implicitly. There is no way to click a link that sends a POST request without intervening with Javascript. Unlike forms, however, links take on the dual role of being both a functional and a presentational element - you can see links on the web page.
Since links can't send anything other than GET requests, we are more likely to use Javascript - assuming we want to make a POST request by clicking a link. This gives us full control over the HTTP request. When a user clicks a link, or any other element listening for click events, some Javascript function is triggered that will assemble the HTTP request. The request is then sent asynchronously behind the scenes. This work flow is especially easy with libraries such as jQuery. All it takes is a few lines of code to build the request and send it.
There is nothing inherently wrong with this approach - only writing code to do exactly what a form does is discouraged. This is especially true with GET requests that are sent as a result of user input. For example, we have a page that lists objects in a table. We also have a select element that filters the list by some field. When that selector changes, the page is refreshed with the new GET parameters. The request is triggered by binding the selector change event to a Javascript function. The function then builds the URI and sends the request. Alternatively, the select element is part of a form that stores the URI, and the method. Our function would simply submit the form.
Using forms as they were intended is good web-programming practice. They are perfect for collecting small pieces of information and map well to abstractions that exist on a server. Forms store HTTP methods, action URIs, group input elements, and assemble HTTP requests so that you don't have to. They exist for a practical purpose. Use them to your advantage and you'll be surprised at how much code you don't have to write.
Subscribe to:
Posts (Atom)