From 3b34505d79691f129d7babb5de607c6459ac9f4d Mon Sep 17 00:00:00 2001 From: "reed@google.com" Date: Tue, 7 May 2013 15:59:16 +0000 Subject: [PATCH] add block comment describing sync nature of SkStream git-svn-id: http://skia.googlecode.com/svn/trunk@9039 2bbb7eff-a529-9590-31e7-b0007b416f81 --- include/core/SkStream.h | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/include/core/SkStream.h b/include/core/SkStream.h index 30855b3..f968c46 100644 --- a/include/core/SkStream.h +++ b/include/core/SkStream.h @@ -1,4 +1,3 @@ - /* * Copyright 2006 The Android Open Source Project * @@ -6,7 +5,6 @@ * found in the LICENSE file. */ - #ifndef SkStream_DEFINED #define SkStream_DEFINED @@ -15,6 +13,23 @@ class SkData; +/** + * SkStream -- abstraction for a source of bytes. Subclasses can be backed by + * memory, or a file, or something else. + * + * NOTE: + * + * Classic "streams" APIs are sort of async, in that on a request for N + * bytes, they may return fewer than N bytes on a given call, in which case + * the caller can "try again" to get more bytes, eventually (modulo an error) + * receiving their total N bytes. + * + * Skia streams behave differently. They are effectively synchronous, and will + * always return all N bytes of the request if possible. If they return fewer + * (the read() call returns the number of bytes read) then that means there is + * no more data (at EOF or hit an error). The caller should *not* call again + * in hopes of fulfilling more of the request. + */ class SK_API SkStream : public SkRefCnt { public: /** -- 2.7.4