time.h File Reference

Time-related definitions. More...

#include <stdint.h>

Go to the source code of this file.

Macros
#define	UDIPE_DURATION_DEFAULT   ((udipe_duration_ns_t)0)
#define	UDIPE_DURATION_MIN   ((udipe_duration_ns_t)1)
#define	UDIPE_DURATION_MAX   ((udipe_duration_ns_t)UINT64_MAX)
#define	UDIPE_MILLISECOND   ((udipe_duration_ns_t)1000*1000)
#define	UDIPE_SECOND   (1000*UDIPE_MILLISECOND)
#define	UDIPE_MINUTE   (60*UDIPE_SECOND)
#define	UDIPE_HOUR   (60*UDIPE_MINUTE)
#define	UDIPE_DAY   (24*UDIPE_HOUR)

Typedefs
typedef uint64_t	udipe_duration_ns_t

Detailed Description

At the time of writing, the public libudipe API only exposes support for timeouts, but when a given worker thread awaits multiple timeouts, its implementation is closer in spirit to deadline scheduling. So if the need emerges, support for deadlines would not be hard to add to the public API.

Macro Definition Documentation

UDIPE_DAY

#define UDIPE_DAY   (24*UDIPE_HOUR)

One day

UDIPE_DURATION_DEFAULT

#define UDIPE_DURATION_DEFAULT   ((udipe_duration_ns_t)0)

Default value of udipe_duration_ns_t

When used as a parameter, this function means that the default duration should be used. For timeouts, this is UDIPE_DURATION_MAX.

UDIPE_DURATION_MAX

#define UDIPE_DURATION_MAX   ((udipe_duration_ns_t)UINT64_MAX)

Maximal significant value of udipe_duration_ns_t

When used as a timeout, this value indicates a desire for unbounded blocking i.e. wait indefinitely until the event of interest happens or an error prevents it from happening.

UDIPE_DURATION_MIN

#define UDIPE_DURATION_MIN   ((udipe_duration_ns_t)1)

Minimal significant value of udipe_duration_ns_t

When used as a timeout, this value indicates a desire for non-blocking operation i.e. if something can be done immediately then it is done, otherwise the function should fail with a timeout error immediately.

UDIPE_HOUR

#define UDIPE_HOUR   (60*UDIPE_MINUTE)

One hour

UDIPE_MILLISECOND

#define UDIPE_MILLISECOND   ((udipe_duration_ns_t)1000*1000)

One millisecond

This is the shortest sub-multiple of the second that can reliably be used as a timeout or other form of target duration in udipe. Durations on a microsecond time scale or shorter tend to overshoot by a large margin because many system calls take more than a microsecond to process.

UDIPE_MINUTE

#define UDIPE_MINUTE   (60*UDIPE_SECOND)

One minute

UDIPE_SECOND

#define UDIPE_SECOND   (1000*UDIPE_MILLISECOND)

One second

Typedef Documentation

udipe_duration_ns_t

typedef uint64_t udipe_duration_ns_t

Duration in nanoseconds (0, 1 and the maximum value are special)

This type, which is typically used for timeouts as an abstraction over the many different time formats used by operating system APIs, can encode durations up to a bit more than 584 years.

Because processing a network command takes an amount of time which is much greater than a nanosecond (it's closer to the microsecond scale), timeouts should be understood as a lower bound on the duration for which network operations will be awaited, rather than as an absolute deadline by which a given command should have completed.

The following values of udipe_duration_ns_t will be treated specially:

• 0 aka UDIPE_DURATION_DEFAULT will be translated to the appropriate default duration value for the function or struct member at hand. For timeouts this is UDIPE_DURATION_MAX.
• 1 aka UDIPE_DURATION_MIN represents an infinitely small, instantaneous duration. It would be zero if "zero means default" weren't the custom in C. For timeouts this expresses a desire for nonblocking operation: if the result is ready then it should be returned immediately, otherwise the function should fail immediately with a timeout error.
• UDIPE_DURATION_MAX, which is the maximal value of this type represents an infinitely long duration. For timeouts this expresses a desire for fully blocking oeration: wait for the operation to happen or for an error to prevent it from happening.