Time Zone seems like a simple enough concept. Get offset for a place and add/subtract it from UTC. If you are lucky, you will live your life without knowing more. If you are unlucky, you will face issues in production, and not for lack of trying, internet full of trivia, or list of falsehoods that programmers believe about it, few good articles on how to approach it, but very few resources on how to think clearly about itIf you have tried to understand Time Zone, you likely found a few resources with list of fallacies and what's wrong with Time Zone. If you persist, you will come across suggestions like use UTC for timestamp, and in the best case, articles on how it's more complicated and some useful guidelines.

Time Zone is a result of time, history, geography, politics, technology, population, convenience and more. And although that is a lot of context, the solution itself is not that complicated. This article aims to share a mental model behind Time Zone. It might be incomplete, or wrong, but it should be a good enough starting place, unless you prefer rules, trivia and list of falsehoods as better source of learning.

In this article, we will create a mental modelI think of mental models as the base on which to build your understanding. Details matter. But without mental models, I find the details to be more individual facts than connected information. See Understanding financial functions in Excel/Google Sheets as another example of how mental models help. of Time Zone. Learn how advice like Always save timestamps as UTC may not work for your situation. Look at how to apply the mental model in your application design. We will look at falsehoods, only to learn to ignore them.

To approach this topic, first, we will summarize the historical context of the Time Zone. Next, we will build the mental model. And finally, we will look at applying this model. So let's start with historical context.

Why Time Zone?

The history of Time Zone begins with the history of tracking time. In turn, tracking time is influenced by celestial motion, history, geopolitics and moreTime is a fascinating topic in itself. The scale of it, physics involved, infra around it, history, culture and much more. Hopefully, another write-up in the future.. If you are aware that Time Zone works with UTCWhich follows Gregorian Calendar and 24 hours, 60 minutes, 60 seconds clock. And the occasional pesky leap/skip second., that it defines offset for regions identified by Time Zone ID, and that many Time Zones have rules to adjust their offsets for seasons, all of which can change based on geopolitics and are managed as a dataset at eggert/tz etc, then you can skip to: How we use Time Zone?. Otherwise, this section will help you with brief historical context. Few themes that reappear in this section:

• Time and related concepts were invented in response to our needs for coordination. And evolved into their current form as our needs for coordination evolved.

• Much of how we track time is a result of historical happenstance.

• The universe doesn't care about our convenience, but still we got lucky.

Be advised, this section is full of rabbit holes of topics to dive into :) There are expandable sections called Curiosity; raising questions to help you appreciate the context behind the current choices.

We start with celestial mechanics visible to us.

Sun, Moon, Stars and us

The rhythms of life on Earth are roughly synchronized with

1. Its spin — giving us day and night
2. Its rotation around the Sun — giving us seasons
3. Moon's rotation around it — giving us tides

Our biology has adapted to these cycles. Like being awake/active and asleep/recovering, seasons, crop cycles.

These celestial mechanisms lead to an important part of how we track time: Calendars.

Calendars

The Earth's spin is what we experience as a day. The number of times the earth spins while rotating around the Sun is around 365.2421. The number of days that the Moon does a complete cycle around the Earth is 29.53And these numbers depend on how you count. See: The Earth Moves - Vsauce, Year - Wikipedia.. Notice how these are not whole numbers, and Earth's cycle (365.2421) is also not a whole multiple of the Moon's cycle (29.53). These cycles are slightly out of sync with each other. And these are not stable. Earth's spin is slowing, slowlyHundreds of millions of years ago, a day was only about 22 hours long. The moon is, slowly moving away from Earth. Surprisingly, Earth's motion around the Sun seems to be relatively stableFuture of Earth. Still, these rhythms are roughly in sync, for us to consider them as subdivisions. Days grouped into months, and months grouped into years. We came up with calendars to track these.

Calendars were used as early as 6000BC. Of course, history is a lot more complicated. Different calendars with different days, months, yearsThere are many other calendars, some of them still in use. Calendars through the Ages is an interesting read.. As humanity got more connected (first Julian and later) the Gregorian calendarCalendars are trying to codify celestial mechanics into simple rhythms. Even the Gregorian calendar is an approximation for this, and should work for another few thousand years. became the norm — a historical happenstance.

• What if we lived on a moon circling a planet, which was circling a star?
• What if our planet didn't have a moon?How did we get a moon? and How does it influence us?
• What if we evolved on a moon of an exoplanet, in a multi-start system?
• What if Earths orbit was more elliptical?
• What if another calendar was chosen, instead of Gregorian calendar?
• What if we started colonizing moon or Mars?
• Did people care about birthdays before calendars?

Calendars helped us sync activities across days, months, and years. What about within a day? That's where clocks come in.

Clocks

Clocks also have a long history. Many civilizations developed clocks like water, sand, candle clock, sundials. And used them to divide the day into smaller parts. By the 14th century, monasteries were using Turret Clocks for syncing activities like prayersIn medieval Europe, purely mechanical clocks were developed after the invention of the bell-striking alarm, used to signal the correct time to ring monastic bells. History of timekeeping devices - Wikipedia . Towns started to have clocks in town squares to coordinate activities within them. These clocks were mostly tracking the local position of the Sun. E.g. it wouldn't matter if two towns 200km apart had time differing by <OverNote inlineContent="7 min" overContent={Earth's circumference is . A day has . Assuming the two cities are on meridian, mean solar time difference: .} />. Towns had their own local tracking of time. Meanwhile, clocks were getting more precise and portable, driven by the use case of accurate time for sea navigation.

Somewhere along this journey, 24-hour clocks became prevalent. Note that, like the Gregorian calendar, the 24-hour clock was something we converged on. A historical happenstanceTo read more about the history, try Time's Pendulum - Jo Ellen Barnett or History of timekeeping devices - Wikipedia, 24-hour clock - Wikipedia and more..

• What if Earths orbit time around sun was shorter than it's spin (our day)?
• What if a different clock6-hour clock, Decimal time, Swatch Internet Time, मुहूर्त and more was chosen?
• What if midnight was 6 instead of 12

As clocks improved, we started synchronizing our daily lives based on clock time (Sun became secondary). Meanwhile, the world was getting more connected. Which meant a need for syncing/coordinating across different regions.

Time Zones

It began around the 1850s, when trains started to appear as a mode of public transport. Soon, people could travel between cities. Now people travelling across the city would have to sync their clocks with the city clock. A 7 min difference in clocks between two stations 200km apart, would have lead to confusionSomewhat similar to what we might face with flights today.. Especially with trains needing to synchronize their movements. So, we (mostly countries with railways) came up with a system to have the same time for most cities within a country/region. This was essentially a scaled up version of a town's local time. Time for the whole region was based on the Sun's rhythm at a place in the region Railway made it possible to travel fast enough over long distances to require continuous re-setting of timepieces as a train progressed in its daily run through several towns. Starting in 1847, Britain established Greenwich Mean Time, the mean solar time on the Prime Meridian at Greenwich, England, to solve this problem: all clocks in Britain were set to this time regardless of local solar noon. Universal Time - Wikipedia .

Soon, international travel and communication became frequent enough to standardize on how the clock times across countries are related to one another. With the context of the Gregorian Calendar and 24-hour days, as the world got more connected, Time Zones were invented. We came up with Time Zones to standardize offsets used by countries. Two things were needed for this. One, a timeline that all countries agreed on. This is (initially GMT and later) UTC. And second, offsets from UTC (which we will get to shortly).

UTC

To sync time between different clocks, we required a reference timeline. GMT was this timeline. GMT was based on mean of solar time, as measured from Greenwich. Around the 1970s, we started using atomic clocks, which were good enough to keep time better than solar measurements. UTC (Coordinated Universal Time) is derived from a statistical aggregate of some 450 atomic clocks. UTC became the base of most of our time infrastructure. UTC labels the timeline in terms of the Gregorian calendar and 24-hour clock.

Offsets

With a reference timeline, countries would declare offset for their regions. Here the standardization helped with making the offsets more practicalBy about 1900, almost all inhabited places on Earth had adopted a standard time zone, but only some of them used an hourly offset from GMT. Many applied the time at a local astronomical observatory to an entire country, without any reference to GMT. It took many decades before all time zones were based on some standard offset from GMT or  Coordinated Universal Time (UTC). Time zone. India's offset around 1940 was 5:21:10. Imagine trying to set up an online meeting with that offset in mind. With standardization, India's offset is now 5:30. For synchronization across the world, 5:00 or 6:00 might have been more convenient, but 5:30 probably works better for most of the population in India for their synchronization with the Sun's apparent movement?

• What if we had decided on different clock, like Decimal time?
• What if England was not the most influential nation at the time, and there was powerful civilization at Samoa or Hawaii?
• What if GMT was chosen to be the time at Hawaii?
• What if Time Zone offsets were only allowed to be positive numbers?
• Are Time Zones used with other calendars?

Standardized offsets helped with collaboration/syncing across regions. Unfortunately, the story doesn't end here.

DST

Our planet goes around its star (the Sun), while spinning at a tilt of 23.4°The angle of tilt changes slightly, in a 100,000 year cycle!. This tilt leads to differences in both duration and intensity of Sunlight, through our year-long cycle around the SunThere are a few nice visualizations and explanations of it.. As people started synchronizing their life with clocks (instead of the Sun), we started noticing that the Sun was still out, while the clock said night. DST was/is an attempt to help people synchronize with more sunlight in the eveningMore recently, the concept of "Daylight Saving Time" (DST) or "Summer Time" was adopted as a way of allowing people more sunlight hours in the evening. DST varies from country to country (not to mention locality-to-locality) and often has "special one-off" changes to accommodate special events. Not all regions observe DST: usually those closer to the equator do not need it. Working with Time Zones - W3C .

Consider the year 2023 in Los Ángeles (America/Los_Angeles). On Sunday, 12 Mar 2023, 2:00am, clocks shifted forward by an hour. In other words, clocks went from 1:59am to 3:00am. There was no 2:30 that day. This also means evening timings are shifted 1 hour later, relative to the previous day. The sunset in Los Ángeles, which was around 6pm on 11th March, happened at 7pm on 12th March. And on Sunday, 5 Nov 2023, 02:00am, clocks shifted backward by an hour, from 1:59am to 1:00am. And the sunset, which happened around 6pm on the 4th, happening at around 5pm on the 5th. And, clocks read 1:30am twice, that day.

DST is the reason for most shifts in offsets. It impacts more people, than other non-DST offset changes. Many of the developed countries implement DST. Which means, every year, people in these countries experience offset shift, twice.

Time Zone went south

By now you should have a sense that Time Zone is a compromise around nature's rhythm and us syncing our activities. DST is one part of that compromise. There are some extreme examples of this compromise. North Pole and South Pole. For some part of the year, the South Pole has 24 hours of daylight, and the North Pole has 24 hours of darkness. Vice versa for the other parts of the year. Research stations near the South Pole (Antarctica) often use their country's local time. And every so often, whatever is convenientA fascinating Dec 2023 email thread around Time Zone of an Antarctica research base h/t @Mathew Garret, and another one about time one a research ship. .

• What if most our civilization development happened at the poles?
• What if Earths Axial tilt was 90°, instead of 23.4°Another case of we got lucky.?

It's Geopolitical

Now that we have covered the context for Time Zone (and DST), let's emphasize the role of geopolitics in this. We standardized on reference time. And we standardized the process of getting local time. That is, local time should be defined as an offset to the standard reference time (UTC). But the offsets themselves are decided by the governments. It's a geopolitical concern. If a region splits into two geopolitical regions, it might create a new zone and a new offset. If the people in power of a geopolitical region, decide on changing the region's offset, everybody outside would have to respect the rule to get local time for that region. A DST rule could change. Countries might have disputes over borders. Or have internal disputes. Some people might have to deal with different Time Zones for different activities in their livesThe world’s only ethnic time zone , A tale of 2 time zones in one piece of land . Etc. In other words, we agree on the process of getting clock time (get offset and add to UTC), but the offset itself can change with time.

For all these reasons, it makes sense to consider the Time Zone as an offset followed by a set of clocks (instead of a region), called civil time. Below is a visualization of recorded offset and DST changes in the Time Zone. We still show Time Zones by region, since it's the common use-case. It only shows changes since 1970, as the data is more reliable since then. Hover over a region to see the number of changes. Click on the region to open up the relevant part of the tzdb, which has offset rules and comments.

With this context, let's understand how Time Zones are used.

How we use Time Zone

We will only consider Time Zones from an application development perspective. There are four broad use cases.

1. Get civil time (official time followed by a region) from UTC (UTC → CT).
2. Vice versa (CT → UTC) for a particular region
3. Convert between civil times (CT1 → CT2).
4. Do arithmetic like UTC + Duration or CT + Duration.

Let's start with the straightforward case: UTC → CT.

UTC → CT

Previously, we saw that civil time is UTC plus an offset (thanks to standardization efforts). So, if we can get an offset for a region, we can add it to UTC to get the civil time. Here is a representation of this simple model. We will build on it as we add more details.

The first problem we face is the geopolitical nature of regions. Time Zone could have been defined for geographical boundaries. But as the definition of a region can change (or, be contested), it makes sense that we have an indirection: Time Zone ID. Time Zone ID usually refers to a region, but could be used independent of it. Your browser reports as your Time Zone ID, likely set in your operating systemIf configuration or users choice is not available, you can use maps which chart out the region boundaries, and use geolocation with the map to get the Time Zone. Another less reliable way is to use IP address to guess Time Zone or use services which do that or some edge computes.. The list of Time Zones along with their details is maintained at (tzdb) eggert/tz provided by IANA. The visualization we saw before is built on this data. Another one is being maintained by Microsoft, for its OS. We are going to assume IANA tzdb for this articleSame mental models should apply to Microsoft version also. Although, I don't understand why Microsoft keeps a separate data set with it's own maintenance issues. You might be better off using NodaTime or other alternatives. And while we are at the topic of time zone data set, Rails has its own subset of Time Zones and naming convention. 🤷.

So, instead of region, we use Time Zone ID, which represents a region (or occasionally a set of clocks in a region). Given the Time Zone and the UTC timestamp, we want to derive the civil time. As mentioned before, Time Zones themselves are a geopolitical concern. This means offsets can change with time. These changes are also maintained at eggert/tz. But it has a bigger implication. To get the offset, we also need to pass in reference time (because the offset could have been changed after or before that). So, our new model becomes: pass Time Zone and UTC, to get the offset for a region (which uses tzdb) and then add the offset and UTC to get the civil time.

What about DST? DST is like a planned offset change, that applies every year. These are recorded as rules in tzdb. E.g., based on the rule, the time might shift forward or backward (usually by an hour, but could be more or less). For practical purposes, one can consider them to be offset changes. So, our mental model doesn't change.

CT → UTC

This sounds simple enough, and it is until we consider the reverse. Converting from civil time to UTC (CT → UTC). This conversion would have been straightforward had the offsets remained unchanged. Unfortunately, as we saw earlier, the offsets change, and many regions follow DST. These offset changes lead to a shift in local time. Either forwards or backwards. Let's look at the implications visually.

UTC is always moving forwardexcept for leap seconds and it's affect on Unix timestamp, cover later in Unix timestamp and leap seconds. The timeline for civil time can have gaps and overlaps. This leads to three possibilities when trying to convert local time to UTC.

1. If there are no offset changes, civil time maps to UTC. This is the first case in the visual.
2. A civil time could be invalid (no corresponding UTC time). This could happen if civil time is user input. The second case in visual.
3. Civil time could map to two UTC timesWell, it's possible that a country might decide to move back their civil time by 1 hour, but one hour after the offset change, decides to move back 1 hour again, and one hour after that, decides to move back 1 hours for the third time. What's the maximum UTC timestamps that could map to same Civil time? Granted this would be super confusing. And only done by a country trying to sabotage itself. But still, it's a possibility.. This is the third case in the visual.

In more formal language, the function (UTC → CT) is neither one-to-one, nor onto. In other words, its inverse (CT → UTC) is not a function. But, in practice, we can assume that the inverse (CT → UTC) would lead to 0, 1 or 2 UTC timestamps. With 1 being the most common case. This is important in how we deal with Time Zone arithmetic.

The cases of ambiguity and invalidity of CT → UTC is why people suggest keeping time in UTC. We will add more nuance to the topic in the next section.

CT1 → CT2

We looked at UTC → CT and CT → UTC. CT1 → CT2 could be achieved by first doing CT1 → UTC and then UTC → CT2. In other words, first convert from the source Time Zone to UTC, and then from UTC to the target Time Zone.

UTC, CT + Duration

These are operations like adding a month to the time, or adding a day to the time, or adding 300 hours to the timeSee Noda Time documentation on Date and time arithmetic for understanding different kinds of arithmetic. Arithmetic becomes more complicated if we want to accommodate what is intuitive to usSome libraries like NodaTime differentiate between the intuitive arithmetic versus where you add duration without adjusting for intuition. Most libraries do the intuitive arithmetic. If you want explicit arithmetic, you can get the number of days in month and add it explicitly.. When we say same day next month, we usually mean same day from the start of next month, irrespective of whether the current month has 28, 29, 30 or 31 days. Similarly, arithmetic around years should adjust for leap years. Intuitive calendar arithmetic (day, week, month, and year) is common in libraries. Complicated scenarios like the end of next month might be supported by helper functions in the library. Most date-time libraries would support these kinds of calendrical arithmetic.

But when it comes to timezone and time within a day, implementations vary widely. UTC + Duration is somewhat straightforward. There is no offset. We don't need to worry about offset changes. Most libraries could handle UTC + Duration consistently. CT + Duration is more complicated. We will only consider how Time Zone affects these calculations. E.g., the intent of adding a day to a timestamp might be to get the same time the next day. But how should one accommodate for a DST or an offset change within that period? There are a few ways in which software libraries around Time Zone handle this. Remember the three cases? Time Zone can stay the same (in the simplest case). And the other two are: Time Zone offset can move forward, or backward. Let's consider concrete examples. You are in the Europe/Copenhagen Time Zone. Let's say you want to add a day to 2019-03-30 3am. Unfortunately, the offset changed from +1 to +2 on 2019-03-31 2am (civil time). Intuitively, by a day, you probably meant the same time the next day. So adding a day to the time above should result in 2019-03-31 3am. But if we blindly add 24 hours to 2019-03-30 3am, the result would be 2019-03-31 4amSome intuitive operations listed in the next version of browser date and time api (Temporal): Adding or subtracting days should keep clock time consistent across DST transitions. For example, if you have an appointment on Saturday at 1:00PM and you ask to re-schedule it 1 day later, you would expect the reschedule appointment to still be at 1:00PM, even if there was a DST transition overnight. Adding or subtracting the time portion of a duration should ignore DST transitions. For example, a friend you've asked to meet in 2 hours will be annoyed if you show up 1 hour or 3 hours later. There should be a consistent and relatively-unsurprising order of operations. If results are at or near a DST transition, ambiguities should be handled automatically (no crashing) and deterministically.Temporal.ZonedDateTime.add. Different Time Zone libraries handle these cases differently. Here are the behaviours I have come across:

1. Doesn't support it: Noda Time - The library would support other operations like UTC → CT, CT → UTC, and UTC + Duration. You would have to do civil clock time arithmetic using those.

2. Does arithmetic in UTC: Elixir DateTime - Converts the civil clock time to UTC, does arithmetic, and converts the result back to civil time. This means it doesn't adjust for Time Zone shifts. This is the case of 2019-03-31 4am in the example above. The time between start and end will always be 24 hours. Note that because the resulting time is a mapping from UTC → CT, it will never be invalid.

3. Does what's intuitive: Luxon, Temporal - This is the case where the arithmetic above would result in 2019-03-31 3am. When there are two possibilities, Luxon picks the source timestamp offset. To do an explicit operation, you can add duration in hours.

4. Does not support? day.js - The implementation does not adjust for Time Zone offset changes. In dayjs case, the library doesn't support it.

So, if you are working with date time and Time Zone arithmetic, you have to evaluate the library you are using. There are basically two cases the library has to accommodate for. The case where the offset shifts forward. And the one where it shifts back. I have listed three of these cases. Parse these cases with your library and add a day, an hour, etc to understand what the library supports.

For Luxon, Temporal, and DayJS, here is an Observable playground. Dotnetfiddle playground for NodaTime.

Date operations gotcha

If all you care about is date (not time), you have to be careful with timezone arithmetic. Using date & time operations for date arithmetic might lead to some unexpected results, with Time Zone. E.g., if you consider midnight as the start of the day, and you want to find day + 1, but offset changes within that duration, depending on what your library chooses, you might get the same day or next. If you don't care about the time component, and only want to manipulate dates, you may prefer using date operations (if your library supports it) or UTC. Except in rare cases, like the 24-hour shift in Samoa, UTC date calculations should give you the right answer.

We have only covered offset changes in this section. Other kinds of changes, like a new region, although rare, are still possible. If Time Zone is critical for your application, I would suggest spending some time understanding and keeping track of changes.

Application design concerns

With the mental model in mind, while designing applications, we could think of time from two perspectives.

1. Users intent.Jon Skeet brings this up in his writings.
2. Whether the event is in the past or future.

Let's consider the simpler case. Past events. This is where you record the timestamp for when something happened in the past. For example, the time of birth, or when a purchase was made. Recording them as UTC timestamps makes sense. But also, depending on what the user is expecting, you might want to keep a record of the time zone. For example, for a global app, to understand local daily rhythms, it would have to differentiate events based on the region the event happened inHow does Apple Watch Activity app deal with timezone changes?. For many applications, you can save users' time zone in their profile configuration and convert UTC timestamps to civil time, while rendering the UI. But what if a user travels and uses your service? It's a decision you have to make, based on your application and users' expectations.

Next, future events. Timestamps for future events are more complicated. Because the offset could change. For future events, it's important to understand if the user is expecting civil time. For example, if you are a school, you have to respect their civil time. Schools might have 8 a.m. as their opening time. And it might keep it through DST changes (in other words, restaurants open at 8 a.m. based on civil time). Again, you have to think carefully about your applications and users' expectations. And if your user expects local time, you might even have to save the time within the day, for the time zone, and do arithmetic to get what the user is expecting.

Few cases

Let's look at a few cases to get some familiarity. We will assume DST of 1 hour, where applicable.

• Restaurant opening time: You run a real time food delivery app. Customers can order from restaurant based on their operating time. Your region has DST. So, every year, once time moves forward, and once, it moves back. Should your restaurant operating time change based on DST? There is no straight forward answer. It depends on restaurants. Likely, most restaurants would continue to operate the same civil hours, in DST also. And software should implement what restaurants implement in real world.

• Calendar app: A user wants to create a recurring calendar event. Should the event consider civil time or ignore offset changes (in which case the during DST, event would be scheduled 1 hour earlier)? Intuitively, it makes sense to follow civil time. But what if the event is shared with users in other Time Zones? Let's consider another case, where user wants to create a one-off future event. But before the event, government decides to change the offset (or move a future DST earlier). Still, civil time might make sense. Unless the event is shared with people in other Time Zones, in which case, it might make sense to use the UTC time of the future event. From my understanding, Google Calendar saves one-off events in UTC, and uses event timezone for recurring events.

• Counting streak: Let's say you want to track and show study streak (days of study) for students. The students might want these to be counted based on civil timeWhat happens with offset changes? Since we only care about days, this could just be calendar calculations (no need for Time Zone concerns), except for rare cases like Samoa moving forward by 24 hours in dec 2011. Most date time libraries don't handle this case. Likely, the effort of supporting this case, might not be worth the returns.. On the other end, consider GitHub streak. GitHub streaks are recorded based on calendar with UTC+0 offset.

Implementation concerns

With the understanding of how Time Zone affects your application, here are some hints to implementation details:

1. Storing time
2. Transferring time (serialization)
3. Time conversions
4. Updating tzdb

I have only given pointers for these concerns. There are context specific concerns to get into. Before discussing them, we first have to look at the timeline that most systems use in practice: Unix time.

Unix time and leap seconds

Most computing systems don't use UTC directly. That's where Unix timestamp comes in. Unix timestamp is number of seconds since 00:00:00 UTC on January 1, 1970 (the Unix epoch), skipping the leap seconds. Most systems keep track of time as Unix timestamp (or some similar epoch representation). But they also sync time with UTC (remember UTC is timeline that everyone agrees on. Unfortunately, one can't figure out UTC locallyPhysics, Relativity, reality etc.. We have built quite complicated infrastructure to disperse UTC (this includes GPS Satellites). Since Unix time doesn't have the concept of leap seconds, when those happen in UTC, the machine has to do something with it. Common approach was to repeat/skipSkip if negative leap second. There hasn't been a skip second as of the writing of this article. a second, based on leap second. More recent (and better) approach is to spread the leap second across the day. E.g. each second is just a little longer/shorter.).

What does ignoring leap seconds give us? Ease of calculations. Number of seconds in a day is always . But it ignores leap seconds. If you really need precise calculations, like exact number of seconds between two timestamps. You would have to find a way to include leap seconds. You could consider TAI. If you have to record the leap seconds in timestamps and keep track of them in time arithmetic, I wish you luck.

For storage, Unix time representation has different trade-offs compare to the other common representation of time, ISO8601. Unix time is a representation of UTC (which avoids wrong interpretation), but is not quite human friendly. On the other hand, ISO8601 is human-readable but could be interpreted wrongly, and both have slightly different sorting characteristicsFor example, ISO8601 allows for week representation, or skipping separators, adding offset etc. Which lead to different sorting characteristics. If you are using ISO8601 in your application, you also have to understand the context of whether it's UTC or local time. Practically, these are not major concerns since most applications use a subset of ISO8601 representation, and store time in UTC. Timestamps: my strong opinion limited precision (events within a second could be sorted differently. Doesn't support timezone. But creates confusion with offset representation.).

How does this affect time zone. Mostly, it doesn't. Instead of using offset with UTC, offset is applied on Unix time. This leads to leap seconds being ignored in Civil time also. Most libraries around time and Time Zone use Unix time or some similar timeline. Which means, you as a application developer likely won't have to deal with leap seconds. Now, let's get back to implementation concerns.

Storing time

Here mostly you have to understand what information is needed for users intent (or whatever you decided based on that), and how to store that in your persistence layer. Information might be UTC, for most cases. Time Zone (remember to use IANA code) for few cases. And if you are dealing with future recurring times, or future civil time, etc, you might have to consider saving that information also. Or if your use case only deals with date, may be store just the date (without time). As an example, consider a school management software. School timings would usually follow local time and won't change with DST (according to local clocks). What about one-off meetings by teacher/manager in the school? Their repeating meetings would follow local clock (assembly happens based on local clock). So, it would make sense to

Transfer time

You might have to serialize time to transfer or export it. It's best practice to do so in standardized format like ISO8601. Unfortunately, the standard doesn't include Time Zone ID. It supports offset, but by now you should know, offsets can change for a time zone. Different libraries have adopted different conventions. I would suggest following Date and Time on the Internet: Timestamps with additional information which seems to be followed by Temporal and suggested by w3c.

Time conversions

We have already seen that libraries have differences in how they handle certain Time Zone operations. I would suggest to first understand the operations your application might need, and then evaluate libraries for those use cases. I do think the approach used by Luxon and Temporal should work for most cases.

Also, be careful with using time (which includes date), when all you need is date operations. If application only needs Date arithmetic, you could ignore Time Zone (except for the rate cases where Time Zone changes could make a date invalid (Samoa 2011), or repeat (hasn't happened yet)). If you want to support Samoa, you have to get the time zone database and a library which supports arithmetic over time zone.

Updating tzdb

Since the Time Zone database could be updated, for applications dealing with Time Zone, you would have to consider how to update the tzdb periodically. Browsers ship this with their regular updates. Many libraries support updating of the tzdb, e.g Elixir tz, Noda Time.

That covers most of what I have figured out. But I can't end this post without covering the often shared topic around Time Zone - fallacies.

Shall we fallacy?

Somehow it's fashionable to share fallacies around time and related topics. Perhaps we could have implemented better systems, but it shouldn't stop us from building better understanding of current systems. I would rather, people share a mental model which, even if wrong, might lead to more learning (and better mental models) for readers. Dealing with Time Zone (and time) is not intuitive. But complaining about it is not the solution. Anyhow, you can expand the section below to understand how a mental model might be useful to look at, and promptly ignore fallacies.

• A time zone is a numeric offset from UTC.
• Timezone name and abbreviations are unique.
• In the USA, If we know the state a person is in, we can determinate his timezone.
• An entire state follows the same rules for daylight saving time.
• If you know what country a person is. You can determine their time zone.
• There are only 24 time zones possible offer since they are in one-hour increments.
• When DST is in effect, all time zones advance their clocks by 1 hour.
• There can only be two daylight saving time transitions in any given year.
• UTC offsets go from -12 to +12
• Every UTC offset corresponds to exactly one time zone
• There are more countries in the world than time zones
• Every time zone has exactly one agreed upon name
• There is a standard format for declaring time zones
• Daylight Saving Time starts at the same time every year
• A country's time zone never changes
• A country stays in the same time zone during Daylight Saving Time
• Daylight Saving Time starts around March and ends around October
• Every time zone has it’s own name
• Every time zone has its own abbreviation
• Your time zone library can recognize any time zone (you are using a library for this, right?)
• The entire country always shifts during Daylight Saving Time
• The entire state always shifts during Daylight Saving Time
• Other than DST, every city within a state follows the same time zone
• Every city sits within exactly one time zone
• There’s a designated time zone for every location in the world

• Time Zone will never change, so I only have to think about then when I first build my application
• A country stays at the same UTC offset all year long

• There is always an unambiguous conversion from one time zone to another.
• Time zones are always offset from UTC by an integer number of hours.
• Fine, time zones are always offset from UTC by an integer number of half-hours. 😒

A few suggest this in discussions around Time Zone. Why is this not practical? Consider how this would be implemented. All the institutions (banks, government offices, schools, shops, restaurants) would have to change their timings. Population of all nations would have to learn completely new way of talking about their day time. All written references of civil time (a novel charting a characters' day with day starting at 0), would read strange to population which has a different hour for starting of day. I think Time Zone is here to stay. We might make it less annoying, by abolishing DST.

Parting suggestions

Consider Time Zone as a database of mappings from Time Zone ID to offset, which can change with time. Use the database to get the details and keep it updated. Avoid Time Zone arithmetic. And if unavoidable, evaluate the existing libraries, instead of implementing on your own.

Use fallacies to update your mental model. But otherwise, ignore them.

Acknowledgment

Thanks to Saneef, Anantha Kumaran, Dhruva Sagar for reviewing the draft. And especially Arjun Karande for giving much needed critical feedback.

If I did my job rightI am new to these numbers and the approach. If you find mistakes, please do let me know., reading this article, you would have gained a few analogies to work with cosmic numbers. Among other things, you would find that if the history of universe is squished into , most of human advancement happened in last minute. That if we squish a galaxy into the volume of a human being, about million stars would fit in cube. But the star themselves would be smaller than the size of an atom. i.e, most of the space is empty. And that at this scaling, next galaxy would be away.

Experiencing these scales is out of question. But we can build some familiarity and anthropomorphized sense for these scales. Two activities that I have found useful are analogyFor the analogies to work, we have map the numbers to human range. I haven't considered error margins in the calculations. And haven't spent enough effort to be precise. I think it won't be an issue. and playing with the numbers. To get familiar with numbers, you would have to play with them, yourself. Analogies are easier to share and build upon. This article plays with a few cosmic numbers and shares analogies around them, that I have found interesting.

We will get help from a fictitious Celestial Being, referred to as CB in the article, for some of our analogies. And give itTo avoid gender pronoun argument about the celestial being, let's use it to refer to the being. I assure you, it doesn't mind. some supernatural, but limited powers. First power it has is to be able to create universes, as an experiment. Something akin to petri-dish experiments, but at a much grander scale. We will look at CB's perspective on one such experiment (our universe) and our place in it.

We start with time. It's been 14 billion years, since the Big BangWhat happened before then, is CB's concern. when CB started the experiment.

Time

Here is CB's another supernatural power. For it, time seems to be passing much faster. CB started the experiment 72 CB Years ago, with a Big Bang. 1 CB year is equivalent to <OverNote inlineContent={"194 million human years"} overContent={ } /> . A CB year has days, hours, minutes, seconds, same as an Earth for humans1 year is not special from universe perspective. Neither is 1 second. Year is rotation of earth around sun. And second is a convention (or standard?). I use same notion of year and second for CB, to make things more palatable for our mind.. In other words, 1 CB second is about <OverNote inlineContent={"6 years"} overContent={Since 72 CB Years is approximately equal to 14 billion human years. 1 CB second is about or about 6 human years.} /> for humans. We get a year older, and for CB not even a second has passed. In rest of the section, assume all time-scales are CB's perspective, unless explicitly mentioned as human time-scale.

Average human life of 72 years, in CB's time would be <OverNote inlineContent="12 seconds" overContent={Average human life expectancy is 72 years. 72 human years, would be about or 12 CB seconds.} />. So, for CB, here is how timeline of our history would feel like:

• It's been 72 years since experiment started (with a Big Bang). Or the Universe is 72 years old.
• Earth appeared roughly <OverNote inlineContent="23 year" overContent={4.5 billion years ago. or 22 years 5 months in CB's timeline, since experiment start.} /> after Big Bang. Ignoring rest of the universe and focusing on earth.
  • First life appeared <OverNote inlineContent={"53 years"} overContent={3.7 billion years ago. } /> after Big Bang or 19 years ago.
  • Dinosaurs lived and went extinct in <OverNote inlineContent={"year 69"} overContent={Dinosaurs lived somewhere between 245 and 66 million years ago. - 1 year 2 month - 4 months} />.
  • When did human genus come into picture? Around year <OverNote inlineContent={70} overContent={Our ancestors appeared around 2 million years algo. } /> (just 2 years ago from CB's perspective).
  • Our species, Homo Sapiens, only emerged around <OverNote inlineContent={14 hours ago} overContent={Homo Sapiens emerged around 300,000 to 200,000 human years ago. Remember, 1 CB second is about 6 human years. So, Homo Sapiens emerged ago. Or, about 14 CB hours.} />.
  • Most of written human history, around 4000 human years, would be about 11 minutes for CB.
  • In last <OverNote inlineContent={"30 seconds"} overContent={"About 200 human years."} /> , humans learned that the solar system is part of a galaxy with 100 billion stars. And their galaxy is also nothing special but another in 100 billion or so galaxies. And are contemplating the origins of the experiment and much more.

It's fascinating to think how much has happened in last minute, from CB's perspective. Be it the understanding of what is within reach (nature), what is beyond/before/after (universe), what can be (AI, large societies, maths, space exploration) and much more. Human beings have expanded their understanding exponentially, in as many topics.

But, for CB to observe this, it would have to find Earth first. The planet where humans are. A planet, in a solar system, in a galaxy, in the universe.

Counting Stars

We will start by first getting a sense of the number of stars in the universe. Earth is part of a solar system with other planets and one star (Sun). Sun is one among 100 billion other stars in the Mikly Way galaxy. Milky Way itself is one among 100 billion galaxies in the universeThat we know these numbers is in itself interesting. So, in total, 100 billion * 100 billion stars in the universe. Building intuition around this number is going to be difficult. But let's play with these numbers.

First let's get some familiarity with billion.

Few billions

Human population around 9 billion right now. Let’s give each person 1 meter and make them stand one beside another, in a line. How long would that line be? That line could circle the earth <OverNote inlineContent={"200 times"} overContent={ or } /> . If you could walk (without sleep) at 5 km/hour you can cover the circumference in 8000, or about a year (with few short breaks). What would be your age, 1 billion seconds after you are born? Answer: About 31 years, 6 months. Assuming 72 years as average age, most of us live about 2.27 billion seconds. Shake hands with one person for 1s, how long will it take to shake hand with all the humanity. That would be about 253 years. Definitely not something we have intuitive sense of. But, gives us a reference point to play with the number of stars in the universe.

Back to stars

Let's give CB another super-power, with limitation. It sees galaxies as we see our bodyHere is another fascinating scale. Our body houses around 30 trillion cells.. As an example, Milky Way galaxy filling a persons body. I will call this galaxy bodies. One galaxy is one galaxy body. Observable universe is galaxies. Or about <OverNote inlineContent={} overContent={"Rounding human population to 10 billion. 100 billion galaxies is 10 times that."} /> times the human population. In total there would be about 10 times human population galaxy bodies100 billion galaxies, round human population to 10 billion. That means about 10 times as many galaxies as humans.

Now consider all the stars in one galaxy body. That’s 100 billion stars packed one besides other, in our body. Imaging a small centimeter cube on your fingertip, that would be around <OverNote inlineContent={"1 million stars"} overContent={One way to calculate this is first get volume of human body, in and divide the number of stars in a galaxy with it. First, volume of human body. One way is to calculate it with density and mass of human body. Let's say average mass is 75 kg and density close to . So volume comes out to be or . Converting to centimeters . Dividing number of stars in a galaxy with the volume, or . A million stars in a centimeter cube.} />. We are ignoring distance between the stars. We will look at distances in next section.

So, Earth would be somewhere in the Milky Way galaxy body. Let's say at the tip of a finger. CB doesn't know where exactly to look, so it will have to look one star at a time (given no waves or communication). Let's hope for the fictitious entities' sake, there are more planets with lifeSee: https://inference-review.com/article/a-lonely-universe.

But if only earth has life, assuming the celestial being can scan 1 star a CB second, a galaxy body would take it around <OverNote inlineContent={ } overContent={1 second per star. 100 billion stars. So, 100 billion seconds. That is about 3000 years.} /> . That's 1 galaxy. Even if we assume that CB would find Sun after groing through half of the galaxy bodies, it will still take <OverNote inlineContent={ } overContent={ } /> to find Sun. The being would have to be immortal, with abundant patience. Hope the human race survives that long.

But that's not the only concern. Stars are not packed together, like cells in the body. There is a lot of space between them.

Space

Within the galaxy body, if we scale the stars in proportion to the space available to them, the size of the stars would be about . That is smaller than an atom. I.e. most of the space inside galaxy body is empty. Yet, there are a million stars in it. On the other hand, if CB looks for neighboring galaxy bodies, they would be around away. At the scale of stars, space is mostly empty. But at the scale of galaxies, space is quite packed. And all of the observable universe would have a width of <OverNote inlineContent={ } overContent={Observable universe is wide. We are mapping wide galaxies to about . So, universe would be wide. Or about wide. } />. Let's work this out step by step.

Moon is about away from Earth. That's big enough to fit in <OverNote inlineContent={"30 Earths"} overContent={Earth diameter is . Diving distance by Earth's diameter, , or about Earths.} />. Sun is away from Earth. Proxima Centauri, Sun's nearest neighboring star, is away. It's going to be difficult to deal with distances in .

Instead, astronomical distances are mostly measured in light-yearsThere is also AU and cool-sounding parsec. You should check them out.. Let's start with speed of light. Light travels at about , or . Speed of light is the fastest speed that can be achieved in our universeWith consequences like special relativity. Another fascinating topic to explore. Cars do about or . Fastest speed a man-made object has achieved is about , or . It's a probe in space. And it's only of the speed of light.

What does speed of light have to do with measuring space? Light from moon takes 1.3 seconds to reach earth, covering . Light takes about 8 minutes to reach from Sun to earth, covering . Light-year is the distance light travels in a year31 million seconds in a year. So, light travels or about in a year.. Light takes to reach from Proxima Centauri to Sun, covering . I.e. Proxima Centauri is away from Sun. Using makes cosmic distances easier to deal with. After all, light from the stars and galaxies, is how we know what we know about the universe. Now we are ready to look at cosmic distances.

Let's assume stars, on average, are the size of Sun. About in diameter. And separated from closest star by let's say 5 light-years. For these cases, the distance between stars is about <OverNote inlineContent={ } overContent={ or . About } /> times the size of the stars. If stars were a meter in diameter, their next neighbor would be about away. For comparison, earth diameter is .

Milky Way galaxy is in diameter. And about 2.5 million light-years from Andromeda Galaxy. Again, I will assume this is somewhat representative of rest of the galaxies on average. The distance between galaxies is about <OverNote inlineContent={} overContent={} /> times the size of galaxies. If galaxies were a meter in diameter, their next neighbor would be 25 meters away. Galaxies are quite close to each other.

Now consider observable universe. It's 93 billion light-years wide. It is related to how old the universe is. The theory is, universe as we know it, started with a big bang, and has been expanding ever since. And we are seeing edges of that universe, with what light could travel in that time. So, universe might be much bigger than whats we can observe.

We figured in last section that a centimeter wide cube in our fictional galaxy body would have about 1 million stars in a galaxy body. Or on an edge of cube, there would be 100 stars, one after the other. Each star has to it. If we scale the star so that represents the distance between stars, the size of the star itself would be in diameter. That is smaller than size of an atom. In other words the 1 cm cube is mostly empty, but still there are 1million stars in it. On the other hand, like we saw in previous paragraph. If the galaxy is 1 meter in diameter, neighboring galaxy would be 25 meters away.

Imagine CB trying to find a planet around a sun (which is barely the size of an atom) in some galaxy body, among 100 billion galaxy bodies. CB would need a lot more super-powers than what we have given it.

Before we part ways

There is much more to explore. Galaxies are moving. Sometimes through each other. Imagine galaxy bodies moving through each other, while distoring each others shape because of gravity. There are planets, stars in different sizes (neutron stars, red giants), black-holes, Nebulae, galaxy clusters and much much more. Worth reading something like Welcome to the Universe: An Astrophysical Tour, to know more.

My intent with this post, was to share some examples of scaling to human range. I find playing with numbers helps in getting familiar with them. Hopefully, this write-up will nudge you towards exploring on your own, if you haven't already.

But I can't stop without pointing out the wonder of our existence. Universe itself is fascinating, on how it came to be, what it is, what it's going to be. The basic elements it's made of, lead to planets and sun. Life happened on at least one of these planets. With all its variety and process, life (or evolution) is fascinating in its own right. Somehow this process created intelligence which can observe and grow new super-powers (technology for both observation and affect) and gain some understanding of both universe and the process of life itself. This is not even scratching the surface of what we have achieved as a species.

Further explorations

Two broad areas that this article covers is playing with numbers and scale of universe.

Playing with numbers

For playing with numbers, here are a few books that you might find interesting.

• Chapter 6. On Number Numbness - Metamagical Themas: Questing for the Essence of Mind and Pattern - Douglas R Hofstadter
• Innumeracy - John Allen Paulos
• Millions, Billions, Zillions: Defending Yourself in a World of Too Many Numbers - Brian W. Kernighan
• The Machinery of Life - David S. Goodsell Cell biology is another fascinating area with scales difficult to experience. The Machinery of Life uses analogy and visualizations to introduce it.

Scale of universe

• Welcome to the Universe: An Astrophysical Tour - Neil deGrasse Tyson, Michael A. Strauss, J. Richard Gott
• Cosmic Distance Ladder - videos
• Powers of Ten™ (1977) - video
• Expansion of the universe, comoving coordinates
• How big is the solar system
• How the Universe is Way Bigger Than You Think

Acknowledgement

Thanks to Anantha Kumaran, Lalit Patel, Rohit Shinde, Saneef and others for their feedback. Much of the blog is influenced by books, videos and writeups by others on the net. Infact, there might be no original idea in this article. Unfortunately, it's difficult to keep track of all the sources.

The paper shows how to implement an arbitrary state machine with distributed process, assuming there are no failuresHow does failure affect distributed systems. We will look at it briefly in the observations section.. Failures are unavoidable in real systems. Which makes this approach of deterministic distribute state machine impractical. Nevertheless the model used to prove the result is still quite useful.

It didn't take me long to realize that an algorithm for totally ordering events could be used to implement any distributed system. A distributed system can be described as a particular sequential state machine that is implemented with a network of processors. The ability to totally order the input requests leads immediately to an algorithm to implement an arbitrary state machine by a network of processors, and hence to implement any distributed system. So, I wrote this paper, which is about how to implement an arbitrary distributed state machine. As an illustration, I used the simplest example of a distributed system I could think of a distributed mutual exclusion algorithm.

-- 27. Time, Clocks and the Ordering of Events in a Distributed System (Emphasis mine)

If you understand that statement, please feel free to jump to the observations sections, and ignore rest of the article.

The Model

In the paper distributed system is modeled as a set of processes communicating with (passing messages to) each other. One way to make such a system deterministic, is to make parts of the systemin this case processes and communication deterministic and combine them in deterministic way.Are there other ways to make system deterministic? See observations for some discussion. This statement might become clear as we go through the article.

Let’s consider processes first. How do we make processes deterministic? A common approach is to model processes as state machinesDeterminism implies that the process can't read clocks or random numbers or cursor position etc. Or at least, they are modeled as input to the system. with messages as being the commands to the state machines. If you haven’t come across state machines, please do read the wiki on it. The intuition is, given initial state, and same sequence of commands, state machine will reach the same state every time you execute it (it’s like a pure function over initial state and sequence of commands).

With processes being deterministic, the only non-determinism that remains in the system, is the order of messages. With network delays, when a message arrives is not deterministic. But, if we can make sure that all processes (which are state machines) execute messages (commands) according to a global order, then we would have a deterministic system. The algorithm is slightly more involved, and covered later in the article.

Before that, how do we get total order for messages. One way is to have a central server to sequence eventsThis is not a distributed algorithm, although, don't rule this out. Many practical distributed systems use some version of this.. Instead, and this is the most interesting part of the paper, the paper describes how we can have globally ordered events, with only local decisions. Thats the purpose of logical clocksCould we use real clocks (all computers have clocks) for ordering events? Well, yes and no. See Real world needs clocks and observations sections for more. . First few sections of the paper are about deriving logical clocks, to get global order for events. Which is then used to build a deterministic distributed mutual exclusion algorithm.

With the context in mind, here is roughly the structure of rest of the post (which mimics the paper).

1. Events
   1. Partial Ordering Define which orders need to be preserved. Paper calls these happened-before relations (e.g. all events in a process are ordered, and messages define ordering between processes).
   2. Logical Clocks Define properties that a logical clock would have to satisfy, to capture causality (the happened-before relations).
   3. Total Ordering Use logical clock and process ordering to get total order.
2. Deterministic Distributed System Use state machine processes and total ordering to define an algorithm for mutual exclusion without any central server or storage.

I will conclude with some Observations around how it connects with other topics in Distributed systems.

1. Events

Events relevant for the paper, are the events around sending and receiving messages. For more details, please read the paper. You could also refer to a more formal coverage at Lamport's Logical Clocks. In all the pictures below, time flows to the right and the horizontal lines represent the different processes (or humans).

1.1 Partial Ordering

First we need to understand which orders are important to preserve. There are primarily two cases. First, events happening in a single process, are ordered. E.g a user request message was received before the database query message being sent to another process. Second, if process sends a message to process , intuitively, events that happened before sends the message, should happen before, events in after it has received the message. These causal relations are formalized in the paper, as below:

3. If and then . Two distinct events and are said to be concurrent if and .

Here is an example with two process communicating. sends a message to , which after some processing, sends back message to . An event happened before another, is there is a sequence of happened before relations connecting them. Few relations: (there is no happened-before relation between and ), , ( happened-before ). <img style={{width: "100%", margin: "0 auto", padding: "1em", maxWidth: 500}} src="/images/tc-po-3.svg" />

1.2 Logical Clocks

The happened-before relations can be mapped to numbers (which are comparable). This would help with implementing them in real systems. The two conditions in the Logical Clocks section define the constraints that such representation should adhere to.

• C1 If and are events in process , and comes before , then
• C2 If is the sending of a message by process and is the receipt of that message by process , then .

Now, what kind of mapping could work for this? Essentially, increment for any event within a process. and if a message is sent, increment before sending. The message itself carries the logical clock timestamp of the sending process. And the receiving process picks a time stamp greater than both the message and its current time stamp max(clock_in_msg, local_clock) + 1. This gives an ordering of the all the messages for which the order needs to be preserved.

Here is a mapping for the happened-before relation we saw earlier. Note that the timestamp for both and is same, 2. This can happen for some of the events across processes, which are not related by happened-before. Which means, we still don't have total order.

<img style={{width: "100%", margin: "0 auto", padding: "1em", maxWidth: 500}} src="/images/tc-po-mapping.svg" />

1.3 Total order

The few cases where timestamp might be same for events across processes (similar to last section), we need a deterministic way to order them. The approach paper uses is to have a pre-determined order for processes. So the total order is given by the pair (time-stamp, process_id). If the logical timestamp clashes, we break the tie with process_id. For the events below, if , where and are process_id for the respective processes, then the global order of events is <img style={{width: "100%", margin: "0 auto", padding: "1em", maxWidth: 500}} src="/images/tc-po-total-order.svg" /> To summarize, we have total order for all the messages and given two events, any process can derive their global order only based on their timestamps and the predefined order of processes.

2. Deterministic Distributed System

We are ready to combine this total order and state machines, to create an arbitrary state machine on a distributed system (set of processes). The paper shows this by implementing a distributed mutual exclusion algorithm.

You should read the paper for the algorithm, but here is my intuition. First the assumptionsAlthough, they might not be necessary. E.g. One can build a reliable messaging service (like tcp) over reliable processes.:

1. Messages between two processes are received in order.
2. Messages are eventually delivered

Moving on to the algorithm, the intuition that helps, is to look at the process locally. Consider a process which has its request as the lowest timestamp on the request queue. Let's say the request has timestamp . Let's also consider another process . If has received a message from with timestamp greater than , then can be sure that no other message with lower timestamp can come from . Similar logic applies to all the other processes. So, executes its request, when its command has the lowest timestamp in the request queue and it has received messages with timestamp greater than from all the processes.

Here is an example. The green events are the message send events for mutual exclusion request. The brown events are message send events after the mutually exclusive block. The green segment of process timeline signifies the time range where the command would be executed. For this example, let's assume , with , , being the process_id for processes , , respectively. Note that the first event for both process and have first request event with timestamp 1. Since , .

<img style={{width: "100%", padding: "1.4em", maxWidth: 600, margin: "0 auto" }} src="/images/tc-po-example-all.svg" />

The same execution is show below with only a subset of events and messages highlighted, which are related to request. <img style={{width: "100%", padding: "1.4em", maxWidth: 600, margin: "0 auto" }} src="/images/tc-po-example-p.svg" />

Now, the same execution with subset of events and messages relevant for highlighted. <img style={{width: "100%", padding: "1.4em", maxWidth: 600, margin: "0 auto" }} src="/images/tc-po-example-q.svg" />

Notice how even though the requests are happening concurrently and process received request from , before request from , completes it's mutually exclusive execution .

Implementing an arbitrary state machine should also be straight forward. E.g. mutual exclusion could be used to decide on which command is executed next, across the state machines. Hence implementing replicated state machine. Although, it could be made slightly faster by send acknowledgement to all process. See Concurrency: The Works of Leslie Lamport

Real world needs clocks

Note also that the algorithm is distributed in the sense that state machine is only cares about sequence of events, not when it happens. But some events might have a happened-before relation in the physical world. E.g you transferring money to a friend and calling them to check it on their end. <img style={{width: "100%", padding: "1.4em", maxWidth: 600, margin: "0 auto" }} src="/images/tc-po-external.png" />

Lamport points out that synched clocks could be used to preserve happened-before relations outside of the system. As an example, with the mutual exclusion algorithm above, the user commands could be run based on the total order (which uses synched clock for timestamps). This would mean, event would be run by the state machine after event since 's timestamp would be smaller than .

Observations

I like to think of TCO paper as a gateway drug to distributed systems. This section might feel a little contrived. But the associations help me think, so why not. I am just starting to explore these topics myself, slowly. So, read it with more skepticism. I will link a few resources which might help with exploring the topics.

• Models of Distributed system: For thinking about distribute systems, it helps to understand the model on which the theory builds. E.g in this paper, the models used is asynchronous communication and no-failure. Asynchronous communication is realistic, but no-failure is not. Communication could be asynchronous, synchronous or semi-asynchronous. Failures can be fail-stop, crash, crash-recovery, Byzantine etc. Understanding the assumptions, helps create a mental model of what is applicable where. In particular, pay close attention to models used in impossibility (see FLP Impossibility below), or in proofs on consensus algorithms. See these lecture notes for some coverage on different models. Realistic model might be semi-asynchronous with crash-recovery.

• Logical clock: the clock described in the paper is usually known as Lamport timestamps. More logical clocks have been formulated. E.g. vector clock, which helps detecting causal relations (Lamport clock only keeps the relation). Check out the wiki on logical clocks.
• FLP Impossibility: The model used in TCO paper assumes no-failure. What happens if failure is part of the model (e.g. more realistic systems)? Turns out, with asynchronous networks and crash fail, consensus can't be guaranteed. But this doesn't mean consensus can't be achieved. The proof for this seems interesting.
• Consensus: Consensus is an important part of distributed system. Although FLP impossibility means consensus can't be guaranteed, but I think the worst case happens only if there is an oracle which knows exactly when to slow down a process. Practically, consensus is used a lot, in fact in almost all distributed systems, consensus algorithms might be involved in one way or the other. In the original paxos paper, this is the synod algorithm.
• Replicated state machine: If you read papers on consensus, you will come across replicated state machines a lot. One could implement a deterministic state machine on a single machine. But to be reliable (in case of failure), data needs to be replicated to more than one machine. Naive implementation of this might lead to inconsistent data on different machines. To have consistent data with replication, consensus is needed (where a set of machines agree on what the current state of the system is). Most protocols like Paxos, Raft maintain a log and use consensus to append to it across the state machines. You could read A Generalized Multi-Leader State Machine Replication Tutorial, which refers more papers on the topic.
• CRDT: Replicated state machines allow for generic fault tolerant systems. It does this by having consensus on append to a command log. But if the commands are commutative, those could be applied in any order. There is subset on optimizations on paxos for concurrent commutative commands, called Generalized Paxos. In the extreme case, if all operations are commutative, then you have this nice situation where you don't need consensus. And replicas can converge on the same state, eventually. These data structures with commutative operations are called CRDT. <>[video] Strong Eventual Consistency and Conflict-free Replicated Data Types</> -- Marc Shapiro
• Clocks: Even with no-fault assumption, TCO paper still points out that clocks are important, to capture the causal relations that are not part of the system. This is an important part of distributed system. Example, Spanner uses synchronized clocks to guarantee that even external causal relations are maintained.

More references

• Oral History of Leslie Lamport - Part 1
• Keeping Time in Real Systems by Kavya Joshi
• Distributed Systems lecture series by Martin Kleppmann

Acknowledgement

Thanks to Akash, Rahul, Rohit Shinde and others for their feedback.

Motivation

To motivate why you should care, here is a made up scenario. You want to invest today and found two options both offering annual interest rate of 10% for 30 years. Your two options are, investment with annual interest paid back to you (I will call this dividend based investment in rest of the article), or compounding interest. Which one would you opt for? Here are the approximate returns to help you decide.

• Dividend: <OverNote inlineContent={<Currency amount={1000 + 100*30} />} overContent={} />
• Compounding: <OverNote inlineContent={} overContent={ }/>

Here is another hypothetical scenario. You have a friend same age as you. Your friend invested at the age of 20. You being lazy, invested your first at the age of 30 (10 years after your friend). Both investments compound at 10% annual interest rate. How much would your respective investments grow to, when you both are 60 years old?

• your friend: <OverNote inlineContent={} overContent={ } />
• you: <OverNote inlineContent={} overContent={ } />

If you delayed your investment by another 5 years (invested at age 35), the return would have been even lower: <OverNote inlineContent={} overContent={ } /> .

Compounding is unintuitive but has real and significant implications. We will explore some of it's characteristics in this article.

• Hovering over charts shows some details.
• Text styled like would show some details on hover (click on mobile/tablet).

Summary

Some financial wisdom, which are based on the compound interest equation:

• Compounding is exponential process.
  • Time matters. Invest earlyIf you start investing at the age of 20, and don't touch the money till 60, you can utilize 40 years of compounding. Later you start, less years for compounding..
  • Every percent in interest rate matters.
• Splitting investment, other things being same, doesn't affect return. A good way to manage risk.

Mental math

If you like doing back-of-the-envelope calculations, you might find these tricks useful.

• Rule of 72: is an approximation on the doubling period of an investment. But this doesn't give you an idea of time value of the investment.
• Doublings: Each doubling period, money doubles. would give you doublings. And would roughly give the multiple by which the investment would grow. This is simpler to calculate if is a multiple of . Few examples of back-of-envelope approximations:
  • 10% investment over 35 years. Doubling period is <OverNote inlineContent="7 years" overContent={ } />. Number of doublings, <OverNote inlineContent={5} overContent={ } />. Investment grows by <OverNote inlineContent={Math.pow(2, 5)} overContent={ } />.
  • 7% has doubling period of 10 years. In 30 years, the investment should grow <OverNote inlineContent={Math.pow(2, 30/10)} overContent={ } /> times. In 40 years, investment should grow <OverNote inlineContent={Math.pow(2, 40/10)} overContent={ } /> times.

Characteristics of compounding investments

Now to the main content. We will start with what compounding and dividend based investment mean in this article. Then look at the equation and curves etc.

Compounding and dividend

Dividend based investment, in this article, is used for investments where the interest doesn't get reinvested. You invest , but each year, take out the interest.

By the end of two years, you would have + + , or

In case of compound interest approach, interest made is put back into investment (or is not taken out of the investment).

In this case, by end of 2nd year, you would have + + , or . The difference at 2 years is small. But with time, compounding would return significantly more.

You can learn more about compound interest at Khan Academy.

Equation

Let's first understand the equation for compounding. To understand the equation, let's say you invest , with an interest rate of 10%. We will use <OverNote inlineContent={} overContent={10% interest would mean is 0.10} /> for rate of interest, for the number of years, for the initial amount and for amount at the end of year . Every year, you get interest on money that was there at the starting of the year. E.g.

For the first year:

For the second year:

And so on. If you invest amount with an annually compounded interest , in years the total amount would be:

For dividend based investments, the equation would be:

Multiple

First thing to note is that the return is a multiple of initial investment . All the observations in the article depend on this property. In other words, we can write the equation as:

This means, In terms of growth rate, it doesn't matter whether you invest or . They both grow in the same way. What matters is the interest rate. E.g. if the interest rate is 7%, in the first year both of them would grow to 1.07 times the initial value. In the second year, both of them would be approximate <OverNote inlineContent={1.14} overContent={ } /> . In the third year, both of them would be approximate <OverNote inlineContent={1.23} overContent={ } /> times the initial value. So, for the same interest rate, the more money you put in, the more returns you get.

Another nice property is thatGiven interest rate and duration is same. you can split the money into multiple investments and get the same returns . Ex, you could replace with

This is a good way to manage risk. High interest usually comes with high risk. Putting all the money in a single investment would mean loosing all the money if the fund goes down. Instead, the money could be invested in multiple funds.

The multiple property is applicable for dividend based investments also. E.g.

Rule of 72

This is a way to approximate the doubling time of investment.

Again (I find it interesting and worth repeating): doubling period doesn't depend on how much money you put in. Put as much as you can, you will get double of it, after a doubling period.

Doubling continues

The Rule of 72 gives us a number to compare. It's one doubling time. An important but unintuitive number. With every doubling time, your investment doubles. After doubling periods the investment would be times it's original amount. E.g. doubling time of and don't seem too far apart. But in 12 years, doubling time of 1 year would return <OverNote inlineContent={4096} overContent={ } /> times the original amount. While doubling time of 4 years would return <OverNote inlineContent={8} overContent={} /> times the original amount.

Dividend based investment doubles in yearsPlay with to reason why.. Although it is larger than in case of compounding based investment, but the real difference comes because of continued doubling. Next doubling in dividend happens in . And this keeps increasing for future doublings. For compounding, doubling period remains same. And after doubling periods, investment would return times initial investment. That is the significant difference.

Value of 1%

What difference does a 1% change in interest rate make? Hover over the plot below to see the doubling time for the interest rate.

Notice how when interest rates are low, 1% makes a big difference in doubling period. This was a surprise to me. Although this does mean that 1% matters more for returns, when interest rate is low. Every 1% matters, no matter what interest rate you are getting :)

Value of interest rate

The chart below shows return curves for different interest rates. The higher the interest rate, the steeper the curve.

Value of time

Each of the curves below represents a time period (ex: 40, 30, 20 years). The x-axis is the interest rate, and y is the multiple of the investment. Again, the longer you let your investment grow, the bigger the returns. Note how fast the curve grows for high-interest rates and long periods.

With an interest rate of 12%, after 40 years, your investment would have grown 100 times!

In one table

Here is a table of interest rates, years and returns (as multiple of initial amount) associated with that. The top right cell represents 25% annual interest compounded for 35 years. Initial amount would grow 2500 times. Let's say you invested . That would become .

Value of maths?

Much of what we figured out, is just maths and looking at curves. Let's play around with it a little more.

Where does 72 come from?

We will attempt a close enough answer. Let's look at our equation again.

Doubling means , or . In other we need to solve for:

Taking natural log on both sides.

Or

Now here is a nice trick. Turns out, for small values of , is approximately . Ex, it's 0.01, for it's 0.18, approximately. So, for most practical interest rates, we could just use:

turns out to be 69, so doubling time could be equated to (approximately)

But we have been using 72! Wiki explains the reasons behind choosing 72 (or 70 or 69).

Slopes

Let's again start with the compound interest equation . For a curve, the slope at a point is one way of figuring out how fast change is happening at that certain point. A point in the curve represents some point in time and the change in return at that time. With the slope of the curve, if we assume it to be the same for a year around the point, we can approximate the rate of return in that year, by calculating the change in return.

Derivative gives us the slope curve. Derivative of the compound interest equation:

We learned earlier that for small values of r, could be replaced with . So, we could write the above equations as:

Now, let's consider what this means.

Some thoughts around exponentials

It's relatively easy for our brains to think of linear processes. E.g. what would be your age in 10 years?current_age + 10 Or you get every year as dividend on your investment, how much dividend would you get in total, after 10 years? Exponential processes (like compounding) on the other hand, are not as intuitive, but could have a much bigger impact on our life.

Exponential growth is a process where the growth in quantity is proportional to its current value. E.g. when we say the population is growing 2% every year, we mean the population grows by 2% of what it was, at the starting of that year. Covid-19 growth is proportional to the affected people, given enough population and no preventive measures. Knowledge grows exponentially. If you improve on something by 1% every day, by end of the year, you would be about 36Try doing back-of-the-envelope to arrive at greater than 32 times? Close enough to prove the point. times better than when you started.

What now?

There are many factors to consider for personal finance and investment. Mostly they come down to risk and return (which includes the interest rate, taxes, management fees, entry and exit fees, etc). Personal finance is a big topic. You could probably start by reading discussions at Personalfinance subreddit. But remember, to get the most out of compounding, invest early.

Also, it's interesting to note that throughout the article, all we did was look at the implications of the equation .

Pointers to explore more

• Time value of money
• Rule of 72
• Exponential Growth Arithmetic, Population and Energy (video) talk by Al Bartlett
• Functions and Graphs by I. M. Gelfand, E. G. Glagoleva, E. E. Shnol. A nice book on properties of functions and graphing them.
• Tools
  • Desmos - A tool to chart equations.
  • GeoGebra
  • If you are on macOS, Grapher.app is also good.

Acknowledgment

Thanks to Saneef, Rahul, Anantha Kumaran, Rohit Shinde and many others for their feedback.

This approach mostly follows WhyOfY by Richard P GabrielA somewhat similar approach is followed by James Coglan's blog post.. And watch an interesting talk on it, by Jim Weirich.. We will derive it in JavaScript, in steps. Each step is complete. Click on the 'Edit in JSFiddle' to explore the steps.

Premise & setup

Lets pick a simple example, so we can concentrate on exploring recursion. Given a number, n, return the sum of numbers from 1 to n. To start with, below is a recursive solution for the problem. Individual steps are hosted in JSFiddle, for you to play around.

var sum = function (n) {
    return n === 1 ? 1 : n + sum(n - 1);
};
console.assert(sum(5) === 15, sum(5));

try in fiddle

The process

We have to remove the reference to sum, inside the function, which fortunately leads to the Y combinator. One approach to calling a function, without using its name, is to pass the function as parameter.

var s1 = function (f, n) {
    return n === 1 ? 1 : n + f(f, n - 1);
}
console.assert(s1(s1, 5) === 15);

try in fiddle

We have just moved the function name (reference) from inside the function, to the function call. As a next step, we could pass the function as a curried param.

This helps later, in abstracting the passing of function as parameter, out of the logic for the problem.

var s2 = function (h) {
    return function (n) { // inner function
        return n === 1 ? 1 : n + h(h)(n - 1);
    };
};
console.assert(s2(s2)(5) === 15);

try in fiddle

The double call inside the inner function, is quite irrelevant to the problem of calculating sum. The logic of sum shouldn't know that h(h) gives the next function call. The recursive function should just receive a function, to continue the recursion with. We could abstract that in another function. Ex:

// replace
return function (n) {
    return n === 1 ? 1 : n + h(h)(n-1);
};

// with
return (function(f) {
    return function (n) {
        return n === 1 ? 1 : n + f(n-1);
    };
})(function (n) {
    return h(h)(n);
});

Why not pass h(h) as parameter? Why do we have to wrap it in a function?

Here is the complete version.

var s3 = function (h) {
    return (function (f) { // sum function
        return function (n) {
            return n === 1 ? 1 : n + f(n - 1);
        };
    })(function (n) {
        return h(h)(n);
    });
}
console.assert(s3(s3)(5) === 15, s3(s3)(5));

try in fiddle

In the current version, the function dealing with the sum logic, doesn't have any dependency on context, or specific knowledge about how to get the next function. Lets name it as sum (for the time being). Ex.

var sum = function(f) {
    return function (n) {
        return n === 1 ? 1 : n + f(n-1);
    };
};

This is just so we can see the real changes in code. Here is the recursion with sum.

var sum = function (f) {
    return function (n) {
        return n === 1 ? 1 : n + f(n - 1);
    };
};

var s4 = function (h) {
    return sum(function (n) {
        return h(h)(n);
    });
};
console.assert(s4(s4)(5) === 15);

try in fiddle

To evaluate the recursion, we had to call s4 with itself, ex s4(s4). To not use a name, we would have to abstract it in a function. We can define a function which s4 as parameter, and call it with itself as parameter.

var s5 = (function (f) {
    return f(f);
})(s4);
console.assert(s5(5) === 15);

Expanding the definition of s4 gives.

var sum = function (f) {
    return function (n) {
        return n === 1 ? 1 : n + f(n - 1);
    };
};

var s5 = (function (g) {
    return g(g);
})(function (h) {
    return sum(function (n) {
        return h(h)(n);
    });
});
console.assert(s5(5) === 15);

try in fiddle

We are almost done. Now, we just need to pass the actual function (ex sum in our case) as a parameter. Here is the Y combinator.

var Y = function (fn) {
    return (function (g) {
        return g(g);
    })(function (h) {
        return fn(function (n) {
            return h(h)(n);
        });
    });
};
var sum = function (f) {
    return function (n) {
        return n === 1 ? 1 : n + f(n - 1);
    };
};
console.assert(Y(sum)(5) === 15);

try in fiddle

Or in its inlined form:

((function (fn) {
    return (function (g) {
        return g(g);
    })(function (h) {
        return fn(function (n) {
            return h(h)(n);
        });
    });
})(function (f) {
    return function (n) {
        return n === 1 ? 1 : n + f(n - 1);
    };
}))(5); // => 15

try in fiddle

Explorations

If you would like to think more about this, here are a few thoughts to explore.

1. We have only explored function with single argument. How could we make this work with multiple arguments.

2. Could we come up with a combinator, which doesn't take curried version of sum. Ex a combinator which takes sum defined as function sum(f, n) { return n + f(n-1); } as argument.

DSL details

Lets define a Mocha TDD like DSL, with 4 commands.

describe(desc, fn)
setup(fn)
teardown(fn)
it(desc, fn)

// `describe` could be nested within `describe`, to arbitrary depth. ex:

describe('top level describe', function (){
    // ...
    describe('nested describe', function () {
        // ...
        describe('nested nested describe', function () {
            // ...
        })
        // ...
    });
    // ...
});

Each describe could have setup, teardown, it and well describe calls.

All functions registered to setup should be run first. Then all the tests registered with it, and then all the nested describe have to be executed. After all that, function registed to teardown should be executed. Ex:

• Setup
• Execute all the test in the level
• Execute all nested levels
• Teardown

So, how do we solve it.

Lets first think just one level (ex: ignore nested describes). We would have to collect all the DSL commands at that level, and then execute them in a specific order. Note that we can't just execute the commands in the order we come accros. Example, a setup might come after tests (it). But all the setup in a level have to be run before the tests. The way I acheive this is to define all the DSL commands as functions which save the command, and its arguments, to be executed later. ex: setup(fn) would save a pair ["setup", fn]. ex:

// 'key' being the dsl command, and 'val' arguments
function spush(key, val){
    stack[stack.length-1][key].push(val);
}

We will come to the stack part later. Now, once all the commands in a describe level are collected, they are to be executed one by one. Execution of setup and teardown commands is simple. Just execute the function registered with them, in the context (there is a single context, on which all setup and teardown work). Test (functions registered with it) are executed by running the registered function, and showing success or failure based on output. For now, it just checks for the exception thrown by the function. Ex:

function reportTests(fn, desc) {
    desc = test_title(stack, desc);
    try {
        fn.call(ctx);
        success(desc);
    } catch(e) {
        failure(desc, e.message);
    }
}

Describe is the special case. Executing it, essentially means doing the above, at the nested level (ex: the function registered with the describe). Note that teardown should run at the end. So, some information about the current level has to be saved, till all the nested levels are done. This is the reason to have stack, to keep the commands. describe is kinda the main function of the DSL.

function exec_describe(title, tfn) {
    stack.push(new_top(title));
    // collect 'describe', 'setup', 'teardown' and 'it' for the
    // current level
    tfn.call(ctx);
    exec_top();  // execute them
    stack.pop();
}

Well, thats mostly it. There are some small details. Like directly executing the describe the first time we come across it (the process has to start somewhere). Or printing the titles etc.

Full code below.

const success = desc => console.log(`${desc} : Pass`);
const failure = (desc, msg) => console.log(`:( ${desc} : Fail => ${msg}`);
const log = desc => console.log(desc);

const activity = {};
const stack = [];
const isEmptyStack = () => stack.length === 0;
const stackTop = () => stack[stack.length - 1];
const ctx = {};

const spush = (key, val) => stackTop()[key].push(val);

const indentedTitle = ctxt =>
  `${stack.map(() => '   ').join('')}${ctxt}`;

const newTop = title =>
  ({ title, tests: [], setup: [], teardown: [], testSuites: [] });

const execTop = () => 'setup tests testSuites teardown'.split(' ')
  .forEach(key => stackTop()[key].forEach(activity[key]));

const execTestSuite = (title, testSuiteFn) => {
  log(indentedTitle(title));
  stack.push(newTop(title));
  testSuiteFn.call(ctx);   // collect testSuites, setup, teardown and it.
  execTop();               // execute them
  stack.pop();
};

const reportTests = (fn, title) => {
  const desc = indentedTitle(title);

  try {
    fn.call(ctx);
    success(desc);
  } catch (e) {
    failure(desc, e.message);
  }
};

activity.setup = fn => fn.call(ctx);
activity.teardown = fn => fn.call(ctx);
activity.testSuites = ([title, testFn]) =>
  execTestSuite(title, testFn);
activity.tests = ([title, testFn]) =>
  reportTests(testFn, title);

export const test = (desc, fn) => spush('tests', [desc, fn]);
export const testSuite = (title, testfn) => {
  if (isEmptyStack()) {
    execTestSuite(title, testfn);
    return;
  }

  spush('testSuites', [title, testfn]);
};
export const setup = spush.bind(null, 'setup');
export const teardown = spush.bind(null, 'teardown');

Its nice to find out that an expressive DSL could be implemented (to atleast experiment) in less than 100 lines of code.

The script below defines procedure showalltbl to get above mentioned summary for all the tables, that are passed as comma separated list to itCould have achieved the same result in Ruby. But well..

-- ref: http://stackoverflow.com/questions/7737970/procedure-to-loop-through-comma-separated-string-is-not-working
-- ref: http://www.java2s.com/Code/SQL/Procedure-Function/EXECUTEdynamicSQLcommand.htm

delimiter $

drop procedure if exists execsql$
create procedure execsql(q varchar(1000))
begin
      set @q = q;
      prepare stmt from @q;
      execute stmt;
      deallocate prepare stmt;
end$

drop procedure if exists showtbl$
create procedure showtbl(tbl varchar(100))
begin
      call execsql(concat("select \"", tbl, "\""));
      call execsql(concat("select count(*) as entries from ", tbl));
      call execsql(concat("select * from ", tbl, " limit 10"));
end$

drop procedure if exists showalltbl$
create procedure showalltbl(strids varchar(1000))
begin
  declare strlen    int default 0;
  declare substrlen int default 0;
  declare tbl varchar(100) default "";

  if strids is null then
    set strids = '';
  end if;

do_this:
  loop
    set strlen = char_length(strids);

    set tbl = substring_index(strids, ',', 1);
    call showtbl(tbl);
    set substrlen = char_length(tbl)+2;
    set strids = mid(strids, substrlen, strlen);

    if strids = null then
      leave do_this;
    end if;
    if strids = '' then
      leave do_this;
    end if;
  end loop do_this;

end$

delimiter ;

How does this work?

There are three functions defined in the script. The most basic being execsql. Let me start there. Its job is to take a string, and execute it as an SQL statement.

Next up is showtbl. It takes a table name as string. Uses execsql to select that string (so, the output shows the table name, to understand which table rest of the summary belongs to). Selects count on the table. And the show 10 entries from the table.

The last one is showalltbl, which takes the comma separate string of tables. Splits them and calls showtbl on them.

Check the Github repo for installation and usage instructions.

Core idea of the solution is that a client from localhost could keep a connection with a server on the internet.

This connection could be used by server to forward requests. Gotunnel utilizes this by running a client on localhost. This Gotunnel Client connects to the Gotunnel Server accessible on the net. It also connects to the App server. Gotunnel Clients role is to receive requests from Gotunnel Server, and forward them to App Server.

Lets start with a (slightly incomplete) picture of the whole architecture. (Except for small changes, picture is copied from Localtunnel protocol doc). Keep this picture in mind, while we delve into more details.

.
             +--------------------+
             | Gotunnel Server    |
             |--------------------|         +---------+
             | Backend | Frontend |<--------+ Browser |
             +---------|----------+         +---------+
                ^  ^^
                |  ||
                |  ||
         Control|  ||Proxy
      Connection|  ||Connections
                |  ||
         +------|  ||-----------------------------------+
         |   +--|--++----------+         +------------+ |
         |   | Gotunnel Client +-------->| App Server | |
         |   +-----------------+         +------------+ |
         |                                              |
         |                  localhost                   |
         +----------------------------------------------+

What we want is for the App Server to be accessible from (lets say) a browser. Since it can't be accessed from outside the localhost, we have a client in localhost, which is connected with the Gotunnel server, and can connect to the App Server whenever needed.

Lets examine the case where only a single App Server needs to be made accessible on the net. The client could (at startup) connect the Gotunnel Server, and setup a Control Connection. Gotunnel Server, on receiving a request from Browser, would let Gotunnel Client know about it, via the Control Connection. Gotunnel Client would respond by creating a new connection with Gotunnel Server, which will we used as a Proxy Connection. Gotunnel Server would then tunnel the request via the Proxy Connection. All this is happening at the TCP level (and hence supporting HTTP/S & WebSocket).

To support multiple clients, Gotunnel would have to differentiate between requests for different App Servers, and keep account of Control Connections associated with respective Clients. Like Localtunnel, Gotunnel Server associates Clients (and in turn App Servers) with subdomains of the Server.

To look at it from another perspective, lets consider the lifecycle of Gotunnel Server and Client. Lets first look at Gotunnel Client. When a client connects to Gotunnel Server, server sends back a subdomain. This is useless to client itself, except to show it on console, for you to share it with others. Any request to that subdomain, server will route to the particular client. And client in turn, to the App server. Response goes back via the same connections.

Gotunnel Server is basically listening for two kinds of connections. Its listening for subdomain requests, to route to the particular client, associated with the subdomain. And its listening for connections from new clients, and when a new client connects it assigns the requested (or newly generated) subdomain to the particular client.

All the connection routing etc is done at TCP level. What this means is that the connection, in most parts, doesn't have to worry about the application layer protocol. Example, there is no separate code to support WebSocket. The only part where we have to deal with the application layer level protocol intricacies, is to get the Host. We need the host to get the subdomain, for the request. In case of HTTP and WebSocketWebSocket starts as a HTTP connection. So, the process of getting HOST is same for both., we do this by parsing first few hundred bytes of the request, to get the headers. HTTPS is more difficult. In case of HTTPS headers themselves are (or might be?) encrypted. But in our trials, the host string was still sent in ascii. So, if we can't parse headers, we just fall back to a regular expression match. Since the domain of the request is known, we can be somewhat specific in the regular expression. In other words, if you dont need subdomain parsing, (ex: a server which to which only one client can be connected), then there is no need for parsing. And he solution can be simpler.

Routing at TCP level has atleast one problem. It might not be possible to do connection pooling. Ex: We don't know when a request or response ends (unless we deal with the application layer protocol). So, the only way to know the end of connection, is if the TCP connection is closed. In other words, we won't be able use the same TCP connection to tunnel multiple TCP connections.

Four cards are placed on a square table, one card at each corner. A blind gnome and an evil goblin take turns to play the following game. The blind gnome gets to choose a subset of the four cards and flip them simultaneously. If all four cards are face up, he wins the game. Otherwise, the evil goblin get to rotate the table by an amount of his choice. Show that for any initial configuration of cards chosen by the evil goblin, the blind gnome can win the game in a finite number of steps with a deterministic strategy.

To get a better start with the problem, let me simplify it a little. In the modified problem, the gnome wins if all cards face the same. Example, either all cards face up, or all cards face down. This is a simpler problem.

Now lets take the simplified version. Consider the 4 cards on the table. Removing all the symmetrical configurations, there are just three distinct configurations of cards on the table, apart from the winning configuration. For notational convenience, I will use D for a cards facing down, U for a card facing up.

Case 1: Just one face differs from others.
   |D D|
   |D C|

Case 2: two cards up and two down on the same side.
   |D C|
   |D C|

Case 3: Two cards up and two down diagonally.
   |D C|
   |C D|

The gnome has to know about which kinds of flips matter. He cant judge about which cards to flip, so he only has the option of differentiating flips by count and orientation. Again, there are just 3 kinds of flips that matter. Flipping one of them, flipping 2 diagonally, or flipping 2 sideways.

Now map the transformations possible by these flips on the 3 types of configuration.

1 <-diag-> 1
1 <-side-> 1
1 <-one->  {2, 3, win}

2 <-diag-> 2
2 <-side-> {3, win}
2 <-one->  1

3 <-diag-> win
3 <-side-> 2
3 <-one->  1

Lets map the transformations for a the winning game. We would have to keep track of set possible cases that will occur in each transformation. Observe that case 1 is most distant from wining, case 2 the second most, and case 3 the closest. What we would like to achieve is a way to reduce the possible number of configuration, as we work with transformations. So if there is a case 3, finish off with it and so on. If a win happens in between, game ends automatically. So we only have to consider in the cases otherwise. Here's the solution

{1,2,3} <-diag-> {1,2} <-side-> {1,3} <-diag-> {1} <-one-> {2,3} <-diag-> {2} <-side-> {3} <-diag-> {sure win}

To the main problem. If the only winning position is all faces up, the game essentially remains the same except the number of configurations and transformations. Now the number of combinations that matter is 5. The types of transformations remain the same, except for the special case of flipping all the cards. Its only used in one case. For rest of the configurations, flipping all doesn't change anything. Here's a list cases and the transformations which are useful. I am showing win case if its the only case.

Case 1:
   |U U|   1 <-diag-> {1,2} ; 1 <-side-> {1,2} ; 1 <-one-> {3,4,5}
   |U D|

Case 2:
   |D D|   2 <-diag-> {1,2} ; 2 <-side-> {1,2} ; 1 <-one-> {3,4,5}
   |D U|

Case 3:
   |U U|   3 <-diag-> {3} ; 3 <-side-> {4,5} ; 3 <-one-> {1,2}
   |D D|

Case 4:
   |U D|   4 <-diag-> {5} ; 4 <-side-> {3} ; 4 <-one-> {1,2}
   |D U|

Case 5:
   |D D|   5 <-diag-> {4} ; 5 <-side-> {3} ; 5 <-one-> {2} ; 5 <-flipall-> {sure win}
   |D D|

Now the solution for the original problem. What we would try to do it get all the cases to case 5, and then flip-all. Flip all is represented by fa.

{1,2,3,4,5}
<-fa->   {1,2,3,4}
<-diag-> {1,2,3,5}
<-fa->   {1,2,3}
<-side-> {1,2,4,5}
<-fa->   {1,2,4}
<-diag-> {1,2,5}
<-fa->   {1,2}
<-one->  {3,4,5}
<-fa->   {3,4}
<-diag-> {3,5}
<-fa->   {3}
<-side-> {4,5}
<-fa->   {4}
<-diag-> {5}
<-fa->   {sure win}

Essentially, what we did is to take the following action at each step.

• if: 5 one of possible states then flip-all
• else if: 4 among the possible states flip diagonal
• else if: 3, flip side
• else if: 2 or 1, flip one

So gnome can win the game in 15 steps or less.

If you would like to install the pyPdf package, you would have to copy page4eachXobj function to PageObject in pdf.py and add 'import copy' to the top of the file. While copying, be careful with indentation. After this, my file could be placed anywhere.

The file has two methods to convert 4-up/6-up/... slides to a more convenient one slide per page. First method adv_slide_split gives better output(ex: similar to original slides), but works in very few cases. This method doesn't use the row column information, given at input. Second method slide_split works by dividing the page into equal sized pages, usually not as good as the original 1-up, but works with most of the cases. If possible, the program will use the first method, else the second one.

Rest of the post is about my experience with the problem. Not a required read for using the program.

First off, you need to know that pdf is, in simple words, a collection of data and instructions on how to present the data. Its different/complex from markup languages, as it has to deal with various devices, like printer, and not just the web. And has to be able to represent complex typography and graphics etc, in a concise way.

A pdf file contains lots of <num> 0 obj and endobj pairs in it. Called Indirect Objects, these are used as a reference to objects in the file. Example, from collection of pages to postscript instructions and fonts and colors etc. There are few kinds and types of objects. Name objects starting with '/', dictionary objects enclosed in '<<' '>>' pair, array objects in '[' ']' pair, stream object mostly used for data. For our purpose, these should be enough. Indirect objects making it easy to share objects among objects! <num> 0 R is used to refer to an object. I have skimmed, skipped and missed much of the information. If you are interested, read the manual. Chapter 3 is the most relevant part.

I was lucky enough to stumble upon a nicely generated slide to dig into, similar to this one . A casual look into the raw file shows /Page tags.

7 0 obj <<
/Type /Page
/Contents 8 0 R
/Resources 6 0 R
/MediaBox [0 0 841.89 595.276]
/Parent 9 0 R
>> endobj

With the /Page tags are /Resources with an object reference. The referred object is /XObject dictionary with references to 4 objects.

6 0 obj <<
/XObject <</Im2 2 0 R /Im3 3 0 R /Im4 4 0 R /Im5 5 0 R>>
/ProcSet [ /PDF ]
>> endobj

I removed 3 of them from the dictionary. The pdf file indeed showed only the remaining slide (with empty space for others), while xpdf complained about missing references. Manual mentions that /XObject names external objects. That means the names must be used somewhere else. But searching for those names show only the /XObject entries. Page objects entry in manual mentions that /Contents is where the contents of page are described. But /Contents refers to a /FlateDecode stream (essentially a zipped binary of the description of page). Fortunately, I didn't have to look inside it. Need was just to display those external references, one on each page. The external references in /XObject themselves were of type /XObject.

2 0 obj <<
/Type /XObject
...
>>
stream
...
endstream
endobj

Manual mentions details about the type and how to display it. To have a proof of concept, I changed a Page objects /Contents key to point to a custom stream, and /Page to contain one slide. Here's the output. More work was needed to convert the whole document. New pages would be needed, as each page would have to be replaced with 4 new once, references would have to be updated, page counts at all levels need to be updated, xref would have to be updated etc.

This needed considerably more effort than I intended. Again, fortunately, I came across pyPdf. Its a versatile library. In the README itself, it shows the trick of cropping a page (Although I would call it zooming). So all I had to do was to copy page 4 times and only show relevant part in each of them.

The above method doesn't depend on slides being available as separate resources, but used the concept of MediaBox. So it would work with most pdf files. But, if the slides are available as separate resources, the earlier method results in a pdf closer to the original sources. For comparison of the output, here are slides generated with method using XObject and the MediaBox one. Fortunately the library also makes it easier for me to implement the earlier /XObject method. It depends on the internals of pyPdf implementation. So either you would have to copy it to the pyPdf source file, or import all the internal classes of pyPdf.

One was about a robot starting from top left corner of a matrix, trying to reach the bottom right corner. Robot could only go right or down. The problem was to find the number of unique possible paths. My first thought was to use dynamic programming. Some more thoughts, and I was able to see a pattern in the solution. The basic idea was, like in dynamic programming, to solve the smaller problems first. The observation was that the paths could be calculated one level at a time. The paths are calculated along a line parallel to the anti-diagonal, as it sweeps through the matrix from destination cell towards the starting cell.

Here's the code doing just that.

int main(int argc, char ** argv) {
  int r, c, i, j, diag;
  unsigned long long *pa;
  assert(argc == 3);

  r = atoi(argv[1]);
  c = atoi(argv[2]);

  diag = r < c ? r : c;
  pa = calloc( diag, sizeof pa[0] );

  for (i=0;i<diag;i++)
    pa[i] = 0;
  pa[0] = 1;

  for (i=0;i<r+c-2;i++)
    for (j=diag-1;j>0;j--)
      pa[j] = pa[j] + pa[j-1];

  printf("paths %llu \n", pa[diag-1]);

  return 0;
}

The implementation worked for small inputs. But for the actual input, long long was not enough (and assumably intended by the problem designer). Some more thoughts about the process, and the insight came. The pattern seemed to be familiar, although incomplete. It was the Pascal's triangle . It was easy to find out the entry needed from the Pascal's triangle and its corresponding value (). But still, to calculate it, would need more precision than whats available with C data types (otherwise my program would have given the answer). Google also didn't help. Looking for bignum library, lead me to this expression calculator. All I had to do was fill in the equation and copy paste the solution.

The other one was the last problem. Here is a verbatim instance of the problem.

Find the smallest number that can be expressed as the sum of 3 consecutive prime numbers, the sum of 35 consecutive prime numbers, the sum of 553 consecutive prime numbers, the sum of 829 consecutive prime numbers, and is itself a prime number. For example, 41 is the smallest prime number that can be expressed as the sum of 3 consecutive primes (11 + 13 + 17 = 41) and the sum of 6 consecutive primes (2 + 3 + 5 + 7 + 11 + 13 = 41).

The smaller sequence would always end with larger primes, than the longer sequence. Reason being that the same sum is distributed in a smaller set of consecutive primes. How does that help? Slide the smallest sequence to include the next prime, and simultaneously, update all later sequences to have sum greater than or equal to sequences smaller than them. Here's a little cryptic code for the solution.

struct cseq {
  int seql;			/* seq len */
  int seqt;			/* seq top */
  int seqs;			/* seq sum */
} *sa;

void slide_sequence(struct cseq *s) {
  s->seqt++;
  s->seqs -= prime[s->seqt - s->seql];
  s->seqs += prime[s->seqt];
}

int align_to_sum(struct cseq *s, int sum) {
  while (s->seqs < sum) slide_sequence(s);

  return s->seqs == sum;
}

int main() {
  /* initialize sa and primes array and other variables. */

  for each consecutive prime {
    /* invar: bigger sequences have sum >= smaller once. */
    eqcnt=0;

    slide_sequence( &(sa[0]) );

    for (j=1;j<scnt;j++)
      if (align_to_sum(&(sa[j]), sa[0].seqs))
        eqcnt++;

    if (eqcnt == scnt-1) {
      if (isprime(sa[0].seqs) {
        print_sequence(sa, scnt);
        break;
      } else {
        continue;
      }
    }
  }
}

I used an already generated list of primes, from here .

Here are the timing details.

$time ./a.out
seq:     3, start: 221709, end: 221711, sum: 9221231
seq:    35, start: 23088, end: 23122, sum: 9221231
seq:   553, start:  1650, end:  2202, sum: 9221231
seq:   829, start:   930, end:  1758, sum: 9221231

real   0m0.210s
user   0m0.208s
sys    0m0.000s

int tmp = arr[i];
arr[i]  = arr[r];
arr[r]  = tmp;

But, knowing the xor method, I thought why not save a variable. Basically, if a and b are to be swapped, then the code suffices.

a ^= b;
b ^= a;
a ^= b;

So now the question is, would this work on an array. Ex.

arr[i] ^= arr[r];
arr[r] ^= arr[i];
arr[i] ^= arr[r];

Here's a subtle bug. If i and r are same, then it won't. The reason being that we loose the original value. If both indexes are same, the same array entry would be xor'ed with itself. Wiki page explains it better, and why it should be avoided. Again, I learn the evils of premature optimization. Subtleties of programming!

We are given a set of integers, and another integer . And we need to find out if there exists two integers in the set such that there sum is .

Approach:

The straight forward answer is to calculate sum for each possible pair of elements in , and see if any of them matches with .

Note that the sum of the smallest element and the largest element in , will be the median of sums possible with pairs of elements in . If , is less than this sum, then the largest element of could not be in the pair we are searching for. Similarly, if is larger than the required sum, then the smallest element from will not be in the pair we are searching for. The same method could be applied to the subproblem(the remaining list).

At each stage we have to calculate the smallest and largest element in the list. We could solve this for each subproblem in , or we could sort the set initially, and then access the smallest and largest elements in . The second approach solves the problem in .

Coding the approach:

As you might have noticed, the solution is a recursive one. But it doesn't have to be coded that way. The recursive solution could be easily converted to an iterative one, as shown below. I have skipped the much of the code, just to present heart of the method.

int sum_check(int *arr, int n, int x)
{
  int u, l, s;
  u=0;l=n-1;

  while (u<l) {
    s = arr[u]+arr[l];
    if (x < s)
      l--;
    else if (x > s)
      u++;
    else
      return 1;
  }

 return 0;
}

But lets see the recursive approach also.

int sum_check_rec(int *arr, int n, int x)
{
  int s = arr[0] + arr[n-1];

  if (n == 1) return 0;
  if (x == s) return 1;

  return sum_check_rec(arr + (x<s ? 0 : 1), n-1, x);
}

I would not advice you on which approach you should use, but I would like to mention that the usual case against recursion doesn't hold here. At least GCC4.* optimizes tail recursions with optimization level of O1 or larger. Basically, the fact to notice is that the return value of the recursive call is not used by the recursively calling function. Compiler could take the value from the end of recursion to the function which called this recursive function(in essence). Compiler takes over the job of converting the tail recursive call to an iterative version. To make sure that compiler did optimize away the recursion, run the function on an array of size, lets say, 10000. Without optimization, execution of program would give stack overflow error.